# Developer Tooling

Editors, terminals, build systems, package managers, linters, formatters and test runners.

685 instructions from 30 repositories. Last updated 2026-05-08.

---

## Structured, Meaningful Tests

<!-- source: warpdotdev/warp | topic: Testing | language: Rust | updated: 2026-05-08 -->

Tests should follow consistent structure and provide high-signal coverage.

Apply these rules:
1) Put tests in dedicated files
- Follow the repo convention: place unit tests in separate `*_tests.rs` (or `*_test.rs`) files, not inline `#[cfg(test)] mod tests { ... }` blocks.
- Avoid inserting test modules between import statements. If you need a separate file but want to keep the module declaration local, use `#[path = "..."] mod tests;`.

Example pattern:
```rust
// in source file
#[cfg(test)]
#[path = "my_module_tests.rs"]
mod tests;
```

2) Keep tests concise and behavior-focused
- Don’t add verbose scaffolding when a test only needs to prove one meaningful behavior (e.g., “override/clear works”).

3) Consolidate related checks into regression-style tests
- When covering a previously reported bug, consolidate to a single regression test and add a comment pointing to the issue/PR (e.g., `// regression for #10139`).

4) Assert complete, observable sequences
- If logic triggers multiple events (e.g., press + release routing), the test should assert the full sequence rather than only the first effect.

5) Ensure cross-platform coverage when you condition tests
- If tests are excluded on Windows (or made platform-dependent), add Windows-specific unit tests to validate the same behavior/round-trip semantics.

These practices improve maintainability, reduce test brittleness, and ensure coverage remains accurate as behavior evolves.

---

## Config Gating And Validation

<!-- source: warpdotdev/warp | topic: Configurations | language: Rust | updated: 2026-05-08 -->

When behavior depends on platform features, build features, feature flags, or user-provided configuration, keep it explicitly scoped and validated.

Apply this checklist:
- **Gate compilation and code paths**: Put platform/build-specific modules behind the correct `#[cfg(...)]` so non-target platforms don’t even compile unix/fs-only imports.
- **Use the same predicate for behavior**: Action availability should follow the exact feature-flag + settings predicate used elsewhere (and include a correct fallback flow when disabled).
- **Provide deterministic fallbacks**: If a feature like `local_fs` is off, return a safe default (e.g., `None`/empty map) without referencing unavailable functionality.
- **Validate at configuration boundaries**: Parse helpers should enforce invariants (e.g., positive numbers) and surface structured errors.
- **Centralize config source/precedence**: When using env vars or other configuration channels, document and implement a clear precedence model (and consider refactoring into shared “prepare config” logic).
- **Remove or document dead toggles**: Don’t leave production config flags that only exist in tests; either remove them or clearly document which caller toggles them.

Example pattern (cfg + validated parsing):
```rust
// Build gating: don't compile unix-only code on Windows.
#[cfg(unix)]
mod local_api;

// Validation: enforce invariants at parse time.
fn parse_positive_usize_query_param(url: &Url, name: &str) -> Result<Option<usize>> {
    let Some(raw) = url.query_pairs().find(|(k, _)| k == name).map(|(_, v)| v) else {
        return Ok(None);
    };
    let value = raw.parse::<usize>()?;
    ensure!(value > 0, "`{name}` must be greater than 0");
    Ok(Some(value))
}
```

These practices prevent cross-platform build breaks, mis-scoped feature behavior, and silent misconfiguration—while keeping configuration-driven behavior predictable and maintainable.

---

## Extract Shared Helpers

<!-- source: warpdotdev/warp | topic: Code Style | language: Rust | updated: 2026-05-08 -->

When review finds repeated or “very similar” logic patterns, don’t leave copy-paste growth—refactor into a shared helper, and follow local file conventions so future edits don’t diverge.

Apply these rules:
1) DRY similar control-flow blocks
- If two (or more) match arms / branches perform the same orchestration/config/picker-sync steps, extract a helper and call it from each site.
- Keep helper boundaries aligned with ownership (pass only the state/handles needed to avoid accidental drift).

Example pattern (from the style of the suggested refactors):
```rust
// 1 helper used by multiple match arms
fn apply_harness_change<A, V>(
    state: &mut OrchestrationEditState,
    memory: &mut PerHarnessModelMemory,
    handles: &OrchestrationPickerHandles<A>,
    new_harness_type: &str,
    fallback_base_model_id: impl FnOnce(&mut ViewContext<V>) -> Option<String>,
    ctx: &mut ViewContext<V>,
) {
    // ... shared harness-switch logic ...
    // ... update picker/model selections ...
    ctx.notify();
}

// called from different arms
apply_harness_change(
    &mut self.state.orch,
    &mut self.saved_model_per_harness,
    &self.handles.pickers,
    harness_type,
    |ctx| block_model.base_model(ctx).map(|id| id.to_string()),
    ctx,
);
```

2) Avoid duplication for readability
a) Don’t call the same query method in both sides of an if/else—compute once before branching when it’s the same value.
b) If match arms differ only by a small behavior, consider grouping them (or a shared function) rather than duplicating the surrounding scaffolding.

3) Keep file conventions consistent
- Imports: prefer explicit imports at the top of the file over repeated inline qualification.
- Tests: follow the codebase convention (e.g., place test modules/`#[cfg(test)]` blocks at the bottom of the file).

These changes should be “small refactors that prevent future drift”: they improve consistency without altering behavior.

---

## Explicit Missing-State Handling

<!-- source: warpdotdev/warp | topic: Null Handling | language: Rust | updated: 2026-05-08 -->

When data is optional/unknown, handle it intentionally and explicitly—either skip the feature (return `None`) or fall back to a safe default—never via implicit drop or placeholder sentinel values.

Standards:
1) Use `Option` (or “unset” fields) to represent missingness. Don’t encode “missing user” as an empty string; use `Option<String>` (or clear the field) instead.
2) For optional features: return `None` when the input is absent or invalid (e.g., empty/unparseable config) so you don’t inject placeholder context.
3) For UX that must keep working: when an identifier can’t be resolved (unknown profile/name), fall back to a defined default rather than aborting.
4) Enforce invariants in types: if `None` should never occur, remove `Option` from parameters/fields and make it impossible to construct invalid states.
5) Be explicit in branching: enumerate all enum/location/type cases so non-local/null/unknown cases don’t get silently mishandled.

Example pattern (skip-or-fallback):
```rust
fn resolve_profile(agent_profile_name: Option<&str>, default_profile: &str) -> Option<&str> {
    match agent_profile_name {
        None => Some(default_profile),
        Some(name) if is_known_profile(name) => Some(name),
        Some(_unknown) => {
            // Unknown should still resolve to something usable.
            Some(default_profile)
        }
    }
}

fn load_optional_context(path: &Path) -> Option<String> {
    let content = path.read_to_string().ok()?; // absent/IO error => None
    if content.trim().is_empty() {
        return None; // invalid/empty config => None (don’t inject placeholders)
    }
    Some(content)
}
```

---

## Purpose-Driven Documentation

<!-- source: warpdotdev/warp | topic: Documentation | language: Rust | updated: 2026-05-08 -->

When adding or modifying code, ensure comments/doc comments are written to explain meaning and rationale—not just what the code does or where it’s mutated.

Apply this checklist:
- **Explain “what” and “why”**: If behavior becomes more complex or non-obvious, update the associated doc comment to state the rationale (what problem it solves / why complexity changed).
- **Document invariants & ownership**: For fields/state, clarify the field’s meaning and why it exists (e.g., derived/non-canonical vs canonical), and note any expected lifecycle (when it can be removed).
- **Keep comments attached**: Don’t insert unrelated items (e.g., `#[cfg]` helpers) between a doc comment and the item it documents; structure code so the comment clearly binds to the intended symbol.
- **Avoid ambiguous references**: In user-facing or accessibility text, use specific nouns (e.g., the actual tab name) rather than vague pronouns like “this tab.”
- **Justify non-obvious decisions**: For intentional exceptions or UI/logic branches, include short “why” comments to prevent future regressions.

Example (clarifying non-canonical state intent):
```rust
/// Current known statuses as reported to clients.
/// Not the canonical source of truth; once canonical indexing state is wired in,
/// this transitional cache should be removed.
codebase_index_statuses_by_repo: HashMap<String, RemoteCodebaseIndexStatus>,
```

---

## Semantic, Contract-Revealing Names

<!-- source: warpdotdev/warp | topic: Naming Conventions | language: Rust | updated: 2026-05-08 -->

Use naming that matches the code’s actual semantics and data contracts—avoid misleading terms and generic parameter names.

Apply these rules:
- Behavior-accurate wording: don’t use terms like “unset” when the implementation “restores”/“replaces” a previous value.
- Domain-accurate nouns: if something isn’t a true “anchor”, don’t name APIs/vars “anchor”. Use the real concept (e.g., matching header).
- Contract-revealing identifiers: never name encoded/serialized inputs as just `value`; name the expected type/encoding.
- Terminology clarity: avoid vague or unexplained terms (e.g., “frame”) unless they’re widely recognized; otherwise reference the specific control/behavior, often via an enum with variants.
- User-facing terminology: ensure the vocabulary matches user understanding (e.g., prefer a single clear option like “none” rather than confusing “unset” vs “cleared”).

Example (pattern):
```rust
// Misleading: suggests truly removing state when we actually restore.
fn unset_warp_default(&mut self, ctx: &mut ModelContext<Self>) {
    self.restore_macos_terminal_as_default(ctx)
}

// Contract-revealing parameter names.
pub fn format_git_branch_command(encoded_branch: &str) -> String {
    // encoded_branch is a GitBranchOnClickValue-encoded string
    format!("git checkout {encoded_branch}")
}

// Domain-accurate API naming.
pub fn scroll_to_matching_header(&mut self, header: &str) { /* ... */ }

// Clear terminology via an enum when behavior is two-state.
enum FullGridClearBehavior { ClearToTemplate, ScrollIntoScrollback }
```

---

## Deterministic Matching Invariants

<!-- source: warpdotdev/warp | topic: Algorithms | language: Markdown | updated: 2026-05-08 -->

When implementing algorithms for pairing/alignment, matching/routing, search, or event fan-out, require a clearly stated invariant and explicit boundary/edge-case behavior, then back it with targeted tests.

Practical checklist:
1) Define the mapping/invariant precisely
- Pairing/alignment: state exactly how items align (e.g., “pair min(D,A) in order; pad excess with blanks so row indices always correspond”).
- Routing/matching: state the match predicate (e.g., longest-prefix-wins; require path-component boundaries) and tie-break rules.
- Fan-out/lifecycle: state ownership and cleanup guarantees (who subscribes/unsubscribes, what events should reach whom).

2) Make boundary behavior unambiguous
- Search chunking: if scanning in fixed-size chunks, decide whether matches can cross boundaries; if not possible, prove it; otherwise add tests and/or choose chunk boundaries that preserve correctness (e.g., newline-ended chunks if multi-line matches are possible).
- Limits/quotas/fallbacks: when retrying with different parameters (depth/max_depth), model how the limit is consumed and add the rare edge case tests (e.g., “>quota at root”) that can re-trigger failure.

3) Use data structures that support required operations directly
- For subscription/event systems, use bidirectional maps when you need both:
  - fan-out: key -> connections/subscribers
  - cleanup: connection -> keys/subscriptions

4) Test the invariants at the boundaries
- Add unit/integration tests specifically for:
  - excess deletions/additions (alignment padding correctness)
  - chunk boundary match correctness
  - quota-triggered fallback edge cases
  - prefix match boundaries (path-component boundary)
  - unsubscribe/connection-drop cleanup (no leaks, no missed delivery)

Mini example (alignment invariant style):
```rust
// Within each hunk: D deletions followed by A additions.
// Invariant: row indices correspond across panes.
let pairs = d.min(a);
for i in 0..pairs {
  left_row(i) = deleted[i];
  right_row(i) = added[i];
}
// Excess
for i in pairs..d {
  left_row(i) = deleted[i];
  right_row(i) = blank();
}
for i in pairs..a {
  left_row(i) = blank();
  right_row(i) = added[i];
}
```

Adopting this standard prevents “almost correct” algorithms that break only at boundaries (chunk edges, quota-trigger thresholds, prefix boundary rules, uneven hunk sizes) and makes future maintenance safer because invariants are explicit and testable.

---

## Type-Safe API Boundaries

<!-- source: warpdotdev/warp | topic: API | language: Rust | updated: 2026-05-08 -->

APIs that cross module boundaries, wire formats, or event streams should be designed so callers can’t accidentally construct invalid requests or rely on unstable semantics.

Apply these rules:
1) Prefer request objects/enums over ambiguous parameters
- Avoid signatures like `(Option<T>, Option<U>)` when only certain combinations are valid.
- Instead, model the valid states explicitly (e.g., `ReportShutdownRequest`) or split into distinct methods.

Example:
```rust
async fn report_shutdown(&self, req: ReportShutdownRequest) -> Result<()> {
    // handle only valid states; unreachable invalid combinations
}

// vs:
// async fn report_shutdown(&self, error_category: Option<String>, error_message: Option<String>) -> Result<()>;
```

2) Use named fields (and owned inputs) for client interfaces
- Prefer `struct` parameters with named fields so arguments can’t be swapped.
- Prefer owned data (`String`) over `&str` for async/client boundaries unless there’s a strong lifetime reason.

Example:
```rust
pub struct InitializeRequest {
    pub user_id: String,
    pub user_email: String,
    pub crash_reporting_enabled: bool,
}

pub async fn initialize(&self, auth_token: Option<String>, req: InitializeRequest) -> Result<()>;
```

3) Evolve event/wire contracts compatibly
- If changing semantics, introduce an opt-in event/variant rather than overloading an existing one with different meaning.
- Add tests that enforce the old vs new event emission contract.

4) Be cautious with serialization changes
- Adding/altering serde rename behavior can break previously persisted or in-flight data.
- Guard changes with migrations, custom serializers, or compatibility annotations.

5) Keep public API surfaces intentional
- Wrap internal complexity behind a stable facade so consumers use the intended abstraction (and don’t mix incompatible keys/models/types).

These practices reduce misuse at the boundary, make intent obvious at call sites, and prevent subtle regressions when contracts evolve.

---

## Secret and Inert Safety

<!-- source: warpdotdev/warp | topic: Security | language: Markdown | updated: 2026-05-08 -->

When handling auth secrets, user directory/path-based configuration, or shell-generated code, treat any value that could reveal identity/organization or execute code as *sensitive* and *untrusted by default*.

Apply these rules:

1) Define trust boundaries explicitly
- Secret-backed and command-backed values must be treated as inert data during Drive sync/preview/import/shared browsing/metadata rendering.
- Execute or substitute into a live shell session only after explicit user action (e.g., apply/export) and only for content the user owns or has explicitly chosen to trust.

2) Escape/serialize as data, never as code
- For shell code generation (e.g., Nushell): embed dynamic values using the shell-specific literal serializer/escaping contract (double-quoted literal rules, escaping of quotes/backslashes/control chars, and correct string/argument handling).
- Never construct executable snippets by concatenating raw dynamic strings. Prefer binding escaped literals to variables and passing them as arguments.

3) Redact sensitive logs and diagnostics
- Never log raw directory/path keys, secret-manager commands, or secret stdout/stderr.
- For path-derived keys (like directory override maps), log only a stable short redacted identifier (hash) plus non-sensitive value text when needed.

4) Don’t “silently weaken” authorization scopes
- If secrets are personal-scoped by default, ensure the system cleanly supports broader scopes only when explicitly modeled (e.g., team API keys) and never by accident.

Example patterns

A) Redacted warning message (path-key privacy)
```rust
fn warn_directory_override(key: &str, theme: &str) {
  let redacted = redacted_key_id(key); // stable short id; never reversible without a local salt
  log::warn!(
    "directory_overrides[hash={}] : unknown theme '{}' — skipping this entry until corrected",
    redacted,
    theme
  );
}
```

B) Inert secret/command snippets in untrusted flows
- During sync/preview/import: store the *structured reference* (or escaped literal placeholders) but do not persist rendered secret-manager commands or secret output.
- Only after user applies/exports into an owned/trusted execution context, render/execute and keep failure output free of secrets.

Enforcement checklist / tests
- Add tests that assert:
  - Logs/telemetry never contain raw sensitive strings (raw directory keys; rendered secret-manager command; secret output).
  - Shell-generated code treats dynamic values as literals (malicious strings with quotes/$()/'/newlines stay single-statement data).
  - Secret-backed values remain inert through preview/import until explicit apply.
  - Auth-secret scope changes are authorization-driven (no accidental escalation from defaults).

---

## Bounded Recovery With Timeouts

<!-- source: warpdotdev/warp | topic: Error Handling | language: Markdown | updated: 2026-05-08 -->

Implement failure handling so recovery is (1) bounded, (2) never hangs indefinitely, and (3) has explicit validation + deterministic fallback.

Apply this when adding retries, polling for readiness, or supporting boundary-specific execution paths:

- Resource-bounded recovery: if you retry after a known quota/limit failure, ensure the retry does not keep consuming the same global budget. Make the retry’s accounting explicit (e.g., disable quota consumption for a bounded-scope retry or pass the correct remaining quota), and add a regression test for the triggering condition.
  ```rust
  // Pattern: on known limit failure, retry with bounded cost by adjusting quota.
  match err {
    ExceededMaxFileLimit => {
      // Retry only what’s needed at shallow depth; avoid consuming the global quota again.
      entry.build_tree(max_depth = 1, remaining_file_quota = None)?;
    }
    other => return Err(other.into()),
  }
  ```

- Timeout + actionable error: any polling loop / “wait until ready” / session-join wait must have a timeout and surface a clear error state when exceeded.
  ```rust
  let ready = tokio::time::timeout(Duration::from_secs(30), wait_for_ready()).await;
  match ready {
    Ok(Ok(())) => {}
    Ok(Err(e)) => return Err(e),
    Err(_) => return Err(anyhow::anyhow!("Timed out waiting for follow-up session readiness")),
  }
  ```

- Explicit validation and fallback: for boundary-specific spawning (WSL/MSYS2/remote/local) validate required arguments up front and ensure unsupported paths fail predictably (graceful unsupported-shell fallback) rather than relying on implied behavior.

- Test the failure mode: add regression tests that assert the system enters the correct recovered state (or correct failure state) under the exact triggering conditions (quota exceeded, hang/timeout scenario, unsupported-shell spawn path).

---

## Cache invalidation rules

<!-- source: warpdotdev/warp | topic: Caching | language: Markdown | updated: 2026-05-08 -->

Any cached value must have an explicit, testable “when does it become stale?” policy, plus a fallback path when updates may be missed.

Apply this as a checklist:
1) **State the cache scope & dependencies**: What inputs does this cached data depend on? (e.g., harness selection + auth secrets, repo path + embedding config, shared snapshot version, identity key/authorization)
2) **Enumerate invalidation triggers** (at minimum):
   - **Schema/data integrity**: version mismatch, corrupt/missing snapshot files → invalidate and rebuild/refetch.
   - **Upstream configuration changes**: backend config / embedding config changes → mark stale and rerun necessary work.
   - **Source-of-truth changes**: filesystem watcher events, repo path disappearing/not a repo → mark stale and fail over appropriately.
   - **Authorization/root-hash validity**: if the backend rejects or can’t authorize a previously “ready” root hash for a specific identity/user → mark failed and require re-association/rebuild.
   - **Identity changes**: clear identity-scoped client caches; shared machine caches can remain if they contain no user-specific/credential data.
3) **Refresh strategy**: don’t rely solely on “refetch on login”. Use either:
   - **TTL/periodic revalidation**, aligned with existing refresh cadence, or
   - **event-driven invalidation** when you have reliable signals.
4) **Pull-based fallback when pushes may be missed**: when navigating to a new repo/state or reconnecting, issue a **status/read query** if your model might be incomplete or outdated.

Example pattern (Rust-style pseudocode):
```rust
enum CacheState<T> { Fresh(T), Stale { reason: String } }

fn should_invalidate(reason_from_inputs: Option<&str>, integrity_ok: bool) -> bool {
    !integrity_ok || reason_from_inputs.is_some()
}

async fn get_with_invalidation(cache_key: Key) -> Result<Value> {
    let entry = load_cache(cache_key)?;
    if should_invalidate(entry.integrity_ok == false, entry.dep_version_changed) {
        invalidate(cache_key);
        return fetch_from_source(cache_key).await;
    }

    // If push might have been missed or we’re not confident it’s current:
    if entry.age > TTL || entry.last_update_suspicious {
        return fetch_and_replace(cache_key).await;
    }

    Ok(entry.value)
}
```

Result: fewer “mysteriously stale” UIs, safer authorization handling, and consistent behavior across both local and remote/daemon-backed caches.

---

## Bound Large Work

<!-- source: warpdotdev/warp | topic: Performance Optimization | language: Rust | updated: 2026-05-07 -->

When code performs expensive IO/compute or reacts to frequent events, (1) gate side effects to meaningful state changes, (2) bound or chunk large inputs/outputs before allocation or heavy processing, and (3) cache/share to avoid repeated recomputation and deep clones.

Apply this standard:
- Event-driven gating: only do PTY/UI work when the result would actually change (e.g., dark/light classification changed), and prefer granular events or unsubscribe once the relevant phase is reached.
- Input bounding: add explicit max sizes and reject early (prefer stat-first) before reading entire payloads; for media/file inspection, sniff only a small prefix rather than loading whole files.
- Large IO chunking: when a subsystem has practical buffer limits (e.g., PTY proxy), write in conservative chunk sizes with appropriate delays.
- Computation caps: before expensive semantic/entity processing, skip for known large/unsupported cases and cap content size.
- Avoid repeated expensive rebuilds/clones: use caching to avoid per-frame data-structure rebuilds and use Arc (or similar sharing) for expensive-to-clone payloads.

Example patterns (adapt as needed):
```rust
// 1) Gate side effects on meaningful state changes.
let is_dark = theme.inferred_color_scheme() == ColorScheme::LightOnDark;
let should_notify = {
    let mut model = self.model.lock();
    let changed = model.is_dark_mode() != is_dark;
    model.update_colors(colors);
    model.set_color_scheme(is_dark);
    changed && model.is_term_mode_set(TermMode::DARK_LIGHT_NOTIFICATIONS)
};
if should_notify {
    self.write_to_pty(format!("\x1b[?997;{}n", if is_dark { 1 } else { 2 }).into_bytes(), ctx);
}

// 2) Chunk large writes for constrained transports.
const CHUNK_SIZE: usize = 4096;
for (i, chunk) in bootstrap_bytes.chunks(CHUNK_SIZE).enumerate() {
    // spawn/send with a small delay if needed to avoid buffer drops
    send_chunk_with_delay(chunk, i * 50, ctx);
}

// 3) Stat-first size cap before reading full payloads.
let meta = std::fs::metadata(&path_str)?;
if meta.len() > MAX_IMAGE_SIZE_BYTES_FOR_CLI_AGENT {
    show_toast(format!("{} is too large", filename), ctx);
    continue;
}

// 4) Prefix-only sniffing.
let prefix = read_prefix(&path, MIME_SNIFF_BYTES)?;
let mime = infer_mime_type(&path, &prefix);

// 5) Compute caps/guards.
let entity_diff = if content_is_small_enough && !is_large_or_unrenderable {
    compute_entity_diff(&content)
} else {
    None
};
```

Result: fewer wasted computations, less memory churn, and fewer correctness/performance issues caused by oversized payloads or high-frequency event handling.

---

## Graceful Error Semantics

<!-- source: warpdotdev/warp | topic: Error Handling | language: Rust | updated: 2026-05-07 -->

Define and implement explicit, user- and operator-facing error semantics for async/protocol code: handle recoverable/expected mismatches without panicking, make failure outcomes observable, and ensure recovery/retry behavior is bounded and well-specified.

**Apply this standard**
1. **No panics for expected mismatches**: If an input/protocol branch is “unknown/unhandled” but not a security-critical invariant, do not `panic!`/`unhandled!()`. Prefer `return`/`ignore` with `log::warn!` (including the offending parameters) and continue.
2. **Async workflows must specify failure outcome**: For operations like “save”, “open”, “edit apply”, and “send”, always decide one of:
   - **Accept + respond success**
   - **Reject with a client-visible outcome** (and/or a telemetry event)
   - **Discard but explicitly report** (so the UI/workflow can reconcile)
   - **Reconcile by pushing server state** (if clients can be stale)
   - **Retry with bounded backoff** (when transient)
3. **Prevent retry/restart storms**: Any loop that can restart on clean-but-empty/closure states must include an outer backoff or a bounded retry counter.
4. **Add error context to logs/telemetry**: When possible, include the error string (or an error code/category) so failures are diagnosable without reproducing.

**Concrete examples**
- Avoid panic on protocol mismatch:
```rust
('n', Some(b'?')) => {
    match next_param_or(0) {
        996 => handler.report_color_scheme(writer),
        other => {
            log::warn!("Unhandled CSI ? Ps n query: {other}");
            // graceful no-op
        }
    }
}
```
- For edit rejection, never leave clients in an undefined state:
  - Either return a “stale edit rejected” result the UI can act on, **or** push the server’s current content/state to connected clients.
- For restart loops:
```rust
// On Ok(None) / Err, wait a little before re-opening the listener.
self.restart_backoff = self.restart_backoff.next();
warpui::async::sleep(self.restart_backoff).await;
self.start_dormant_claude_wake_listener(conversation_id, ctx);
```

**Checklist**: For any change touching error handling, confirm you can answer (a) what happens on failure, (b) whether it retries/reconciles, (c) how the user/client learns about it, and (d) where the error reason is captured (log/telemetry).

---

## Doc exactness standard

<!-- source: warpdotdev/warp | topic: Documentation | language: Markdown | updated: 2026-05-07 -->

Adopt a “docs must be executable-accurate” standard: treat technical docs/specs/changelogs as part of the product contract, and ensure they exactly match current behavior, supported formats, and rendering constraints.

Apply this checklist before merge:
- **Exact formats and constraints**: Document the real file path/inputs/encodings verbatim; spell out quoting, casing, separators, and normalization rules that would otherwise fail silently. Remove or update examples that imply unsupported behavior.
- **Render correctness**: Use markdown that actually renders in your target UI (e.g., link PRs with `[#1234](https://...)`; prefer Unicode emojis over `:sparkles:` style shortcodes if the renderer can’t resolve them).
- **Keep latest-source parity**: When drafts exist across channels (e.g., Slack vs repo), explicitly sync to the latest intended content; don’t merge outdated emoji/text/version bullets.
- **Spec mirrors UX/implementation**: When product direction changes (modal → inline editor, renamed interaction patterns), update the spec to match the real interaction model and state transitions.
- **Avoid brittle claims**: Don’t encode “too-strong” invariants that the system doesn’t truly own; qualify requirements to what the product guarantees.

Example (configuration doc precision):
```yaml
# Flat YAML map: action_name -> key_trigger
# action_name contains ':' so it must be quoted
"workspace:toggle_ai_assistant": ctrl-s
"editor_view:delete_all_left": cmd-shift-A
"workspace:toggle_command_palette": none
```

Example (changelog rendering):
- Use `[#9275](https://github.com/warpdotdev/warp/pull/9275)`.
- Use Unicode emojis like `✨` instead of `:sparkles:` when shortcode rendering isn’t available.

---

## Cache Key Consistency

<!-- source: warpdotdev/warp | topic: Caching | language: Rust | updated: 2026-05-07 -->

When you cache UI/model state, make the cache key and lifecycle unambiguous:

- **Key boundary:** Perform the cache lookup using the exact key form the cache was populated with. Apply normalization/transformation *after* the lookup (only when constructing the output key/label), unless you also normalize consistently when inserting.
- **Persisted entries:** If a cache/state entry must survive across renders, **insert and retain** a persistent handle/entry on first use. Avoid “transient defaults” that get re-created each render frame.
- **Granular keys:** Use the most granular stable identifier available (e.g., per-message/per-conversation id) so state doesn’t collide.
- **Refresh/invalidation:** Keep refresh logic reachable when upstream data may change externally, and remove cached entries when the underlying entity is deleted.

Example (pattern):
```rust
// 1) Cache lookup should use the cache’s expected raw key.
let candidate = pathbuf; // raw
if let Some(hit) = detected_repos_cache.get(&candidate) {
    // 2) Normalize only when constructing the stable group key/label.
    let group_key = ProjectGroupKey::Root(normalize_project_group_path(hit.path.clone()));
    return group_key;
}

// 3) Persist per-entity state; don’t use a transient default.
self.mouse_states
    .entry(conversation_id)
    .or_default(); // ensures the handle exists and is reused

// 4) Remove on deletion.
self.mouse_states.remove(&conversation_id);
```

Apply this checklist anytime you see `HashMap`-backed state, memoized computations, or “lookup + derived key” flows—most cache bugs here come from key normalization order, missing persistence, or missing refresh/invalidation paths.

---

## SSE and Sync Eligibility

<!-- source: warpdotdev/warp | topic: Networking | language: Rust | updated: 2026-05-07 -->

When implementing networking/event-streaming and bidirectional sync, make event delivery correctness explicit: who owns the subscription, who owns cursor advancement, and whether an event should be echoed back.

Apply these rules:
1) **Differentiate event origin** (server-originated vs user-originated) before emitting a change back over the network, to prevent feedback loops.
2) **Open SSE only for eligible consumers**: exclude passive/shared/remote-run views that don’t actually receive inbox delivery in this process.
3) **Define cursor ownership**: only the component that “owns” the inbox should advance/persist cursors; avoid dormant subscribers that advance the server cursor, which can cause later replays to return nothing.
4) **Trigger on the right event classes**: don’t filter wake/delivery down to a narrow subset (e.g., only message events) if lifecycle/peer events should wake the process.

Minimal pattern:
```rust
// 1) Origin-aware echo prevention
match event {
  BufferEvent::ContentChanged { delta, origin } => {
    if origin == EventOrigin::Server {
      // Don't push back to the server; it's already accounted for.
      return;
    }
    // Push only user-originated changes.
    send_edit_to_server(delta);
  }
}

// 2) Eligibility predicate for SSE
fn is_eligible(conversation_id: AIConversationId, ctx: &AppContext) -> bool {
  let has_consumer = driver_or_view_has_live_consumer(conversation_id, ctx);
  let is_not_passive_remote_view = !is_shared_or_remote_child_view(conversation_id, ctx);
  has_consumer && is_not_passive_remote_view
}

// 3) Cursor ownership: only the SSE owner updates cursor state
if this_process_owns_inbox(conversation_id) {
  persist_cursor_sqlite(conversation_id, max_seq);
  persist_cursor_server(conversation_id, max_seq);
}
```

This prevents the common networking failures implied by the discussions: echo loops in bidirectional sync, SSEs opened for the wrong role, missed wakeups from overly narrow filters, and cursor collision that causes replay gaps after dormancy.

---

## Deterministic CI Gates

<!-- source: warpdotdev/warp | topic: CI/CD | language: Markdown | updated: 2026-05-07 -->

All CI/CD automation should be deterministic, machine-independent, and enforced via failing gates—never relying on “latest tag,” unstated baselines, or author-local tooling.

Apply these rules:
1) Release automation must compute baselines programmatically
- When building changelogs or diffs for a specific release tag, derive the “previous release cut” for that channel, not the most recent tag overall.
- Encode multi-version releases (e.g., `stable_00/01/02`) explicitly in the baseline-selection logic.

2) Standards should be enforced by CI-run checks
- If a rule is hard to review manually (e.g., “use per-tab theme lookup only inside tab content”), implement a custom lint and run it in presubmit as a hard failure (e.g., dylint with `-D warnings`).

3) Test environments must be reproducible
- Pin required tool versions in CI (e.g., Nushell >= 0.109.0 via pinned Nix input / devshell package).
- CI must assert the required version before smoke tests.
- If the binary/tool is unavailable in CI, explicitly skip those tests rather than depending on local developer configuration.

Example (baseline selection + CI gate sketch):
```rust
// Pseudocode for deterministic “previous cut” lookup
fn previous_cut(tag: &str, all_tags: &[&str]) -> Option<&str> {
    let channel = parse_channel(tag);
    // Filter to same channel, then sort by the release-cut identifier
    // (not by the most recent full tag string).
    let mut cuts = release_cuts_for_channel(channel, all_tags);
    // Find the cut immediately preceding the one containing `tag`
    cuts.find_preceding_cut(tag)
}

// CI (presubmit) should fail on lint violations
// cargo dylint --lib appearance_theme_in_tab_path -- -D warnings
```

Net effect: release artifacts are correct, rules are enforced automatically, and CI results match across machines.

---

## Secure Input and Secret Handling

<!-- source: warpdotdev/warp | topic: Security | language: Rust | updated: 2026-05-06 -->

Adopt a consistent rule: anything coming from persistence, other platforms/accounts, terminal escape sequences, or secret-managed inputs must be validated/normalized and handled with collision-safe, non-injectable, non-leaky logic.

Apply this as standards:
- **Path portability & sync safety:** When persisting selections that may be synced, only mark as “syncable” if you can reliably interpret it under the current installation root. For custom theme paths, serialize as relative *only* when the absolute path is under the current `themes_dir()`. Preserve “foreign” absolute paths (don’t attempt partial cross-platform legacy inference).
- **Test traversal + platform differences:** Include unit tests for `..`/parent traversal behavior and add Windows-specific coverage where paths/roots differ.
- **Shell command construction:** Never interpolate user- or data-derived strings into shell commands without a quoting strategy. Use a single helper (e.g., POSIX-safe single-quote escaping) and route all shell-sensitive formatting through it.
- **Secret injection precedence:** When turning secrets into environment/config, define precedence and do not override worker-injected env vars. Insert typed auth secrets atomically, and skip on collisions to avoid unintended behavior or privilege changes.
- **Secret file permissions:** When writing secret-bearing config files, create parent dirs if needed and enforce restrictive permissions (e.g., `0o600`) on Unix.
- **Parsing hardening & logging:** Avoid panics on malformed/unexpected structured input (use bounds checks/early exits). Don’t log raw untrusted substrings at debug/info levels if terminal/PTY content could contain echoed secrets.
- **Endpoint/target allowlists:** Prevent local-only configuration (e.g., local Ollama URLs) from being sent through remote/request settings.

Example patterns (condensed):
```rust
// 1) Shell quoting helper
fn shell_single_quote(value: &str) -> String {
    format!("'{}'", value.replace("'", "'\\''"))
}

// 2) Secret env insertion with collision safety
fn build_secret_env_vars(secrets: &HashMap<String, ManagedSecretValue>) -> HashMap<OsString, OsString> {
    let mut env_vars = HashMap::new();
    for (secret_key, secret) in secrets {
        // typed secrets: if any env var is already set non-empty, skip that secret entirely
        // (and never override existing process env)
        for (env_name, env_value) in typed_secret_entries(secret) {
            if std::env::var(env_name).is_ok_and(|v| !v.is_empty()) {
                continue; // collision: skip
            }
            env_vars.insert(OsString::from(env_name), OsString::from(env_value));
        }
    }
    env_vars
}
```

---

## Serialize async per-key

<!-- source: warpdotdev/warp | topic: Concurrency | language: Rust | updated: 2026-05-06 -->

Ensure async/stateful flows are race-free by avoiding overlapping work for the same logical key and by handling events that arrive before the relevant state is ready.

Practical rules:
- If multiple updates for the same key (e.g., `path`, `session_id`, `conversation_id`) can be triggered concurrently, allow only one in-flight async task per key. Queue subsequent updates and apply them sequentially after the current task completes.
- If an external event can arrive before initialization/handshake finishes, do not drop it due to temporarily-missing state. Buffer the specific safe event(s) and replay/emit them after the session transitions to the ready state.
- Don’t rely on side-effects that normally happen via subscriptions/entry hooks when control flow can short-circuit. Apply the required state change immediately at the callsite.
- Avoid blocking filesystem/UI work: if filesystem checks could require syscalls, perform them off the main thread and/or in bounded async work.

Example (per-key queue to prevent stale overwrites):
```rust
// pseudo-pattern
if let Some(queued) = pending_updates.get_mut(&key) {
    queued.push(update);
    return;
}

pending_updates.insert(key.clone(), Vec::new());
let rules = current_rules.clone();
spawn(async move {
    process_update(update, rules, key.clone()).await
}, move |me, result, ctx| {
    me.apply(result);
    me.drain_pending_updates(&key, ctx); // sequentially process queued updates
});
```

---

## Invariant Diff Matching

<!-- source: warpdotdev/warp | topic: Algorithms | language: Rust | updated: 2026-05-06 -->

When implementing matching/diff logic (especially for code/entities), define and test the algorithmic invariants you rely on, and avoid fragile heuristics.

Apply:
- Use a staged matcher: (1) exact identity, (2) invariant structural equivalence (e.g., rename/formatting-insensitive hash), (3) fuzzy similarity for remaining candidates.
- Define structural hashes by masking the *exact* varying span (e.g., replace the name bytes with whitespace before hashing), rather than using brittle line-based assumptions.
- For “moved”/positional classifications, prefer local/context-based reasoning over global thresholds, and add regression tests for common false positives (like insertion above without reordering).
- If you generate candidates via multiple discovery paths (e.g., tree indexing vs filesystem probing), ensure both paths use the same filtering rules and dedupe inputs before matching.

Example (structural hash rename-invariant):
```rust
fn compute_body_hash_invariant(content: &str, start: usize, end: usize, body_bytes: &[u8]) -> u64 {
    // Mask the entity name span so renames don’t change the structural hash.
    let mut bytes = body_bytes.to_vec();
    // Replace non-whitespace characters in [start, end) with spaces (conceptually).
    for b in &mut bytes {
        if *b != b' ' && *b != b'\n' && *b != b'\t' { *b = b' '; }
    }
    let mut hasher = std::collections::hash_map::DefaultHasher::new();
    bytes.hash(&mut hasher);
    hasher.finish()
}
```

Outcome: fewer misclassified diffs (renames vs modifications vs moves), deterministic behavior, and safer results under edge cases and degraded indexing.

---

## Explicit build configuration

<!-- source: warpdotdev/warp | topic: Configurations | language: Other | updated: 2026-05-05 -->

Build-time behavior that depends on versions, paths, or external metadata should be configured explicitly and reproducibly—never implicitly via network calls or brittle patching.

Apply these rules:
1) Avoid mutable network state during Nix builds/evaluation. If a value (e.g., release/version info) can change, don’t fetch it at build time; instead, pass it as an explicit declared input (or keep it unset and let Nix own upgrades).
2) Prefer configuration knobs (env vars / explicit inputs) over cross-repo string hacks. If another repo needs different paths/behavior for your build, that repo should read an env var and fall back to its current relative defaults.
3) Make pinned external dependencies update-visible. Use explicit flake inputs (even with `flake = false`) so updates go through the normal `flake.lock` workflow instead of hidden `fetchFromGitHub` inside expressions.

Example pattern (replace brittle `substituteInPlace` with upstream env-var overrides):
```rust
// build.rs in warpdotdev/warp-proto-apis (proposed)
use std::path::PathBuf;

fn main() {
  let proto_path = std::env::var("WARP_PROTO_APIS_DIR").ok()
    .map(PathBuf::from)
    .unwrap_or_else(|| {
      // fallback to existing behavior
      let manifest_dir = PathBuf::from(std::env::var("CARGO_MANIFEST_DIR").unwrap());
      manifest_dir.parent().unwrap().parent().unwrap().to_path_buf()
    });

  println!("cargo:rerun-if-env-changed=WARP_PROTO_APIS_DIR");
  // use proto_path...
}
```
Then in your Nix expression, pass the override:
```nix
substituteInPlace "${./path/to/derivation}" {
  # ...
}
# and ensure the derivation sets the env var, e.g. via buildPhase:
# export WARP_PROTO_APIS_DIR=${warpProtoApis}/apis/multi_agent/v1
```

Outcome: fewer surprising build failures, clearer upgrade semantics, and safer, testable configuration changes across repos.

---

## Explicit logging for channels

<!-- source: warpdotdev/warp | topic: Logging | language: Other | updated: 2026-05-05 -->

When log behavior depends on configuration (e.g., `WARP_CHANNEL`) or when scripts auto-select an environment/tool (e.g., which Xcode app to use), make the behavior explicit and observable:

- Handle known values with clear conditional branches (use `elif` for each supported channel/value).
- For any unrecognized/unsupported configuration, emit a warning log so issues are diagnosable.
- Log the chosen option (selected log file, selected Xcode candidate/path, etc.) so users can verify what the script did.

Example pattern (channel-aware log file selection):
```sh
if [ "$WARP_CHANNEL" = "local" ]; then
  LOG_FILE=~/Library/Logs/warp_local.log
elif [ "$WARP_CHANNEL" = "oss" ]; then
  LOG_FILE=~/Library/Logs/warp_oss.log
else
  echo "Warning: unrecognized WARP_CHANNEL='$WARP_CHANNEL'" >&2
  LOG_FILE=~/Library/Logs/warp.log
fi

echo "Using log file: $LOG_FILE"
```

---

## Workflow safety defaults

<!-- source: warpdotdev/warp | topic: CI/CD | language: Yaml | updated: 2026-05-05 -->

{% raw %}
When authoring CI/CD workflows, make configuration choices that (1) match the actual capabilities required by downstream steps and (2) use conservative, contributor-safe defaults for automated cleanup.

- If any step needs historical git data (e.g., `git blame`, changelog generation, diffing across tags/commits), ensure the checkout includes sufficient history (commonly full history via `fetch-depth: 0`) and don’t remove it without verifying the dependency.
- For automation that closes/archives issues or other contributor-facing items, prefer longer response windows unless you can justify more aggressive settings (e.g., give ~1–2 weeks rather than only a few days).

Example (git history):
```yaml
- uses: actions/checkout@v4
  with:
    ref: ${{ needs.analyze.outputs.analyzed_sha }}
    fetch-depth: 0  # required for git blame/history-based steps
```

Example (conservative stale closure):
```js
const LABEL = 'needs-info';
const BUSINESS_DAYS = 10; // ~1–2 weeks; adjust only with a strong reason
```
{% endraw %}

---

## Explicit Partial-Success Semantics

<!-- source: warpdotdev/warp | topic: API | language: Markdown | updated: 2026-05-04 -->

When an API operation can be “partially successful” (or yields an empty but non-error outcome), encode that distinction explicitly in the response/protocol so callers can take correct next actions.

Apply this standard:
- Never use a plain `Success` with an empty result to represent distinct conditions like “requested line range is beyond EOF”.
- If the system must return per-item results while still reporting per-item problems, extend the *Success* shape with a dedicated field (e.g., `missing_ranges: [...]` / `failed_ranges: [...]`) instead of forcing an all-or-nothing `Failure` or misusing an existing field with different semantics (e.g., treating “range missing” as “file missing”).
- Keep server/protocol status modeling explicit and stateful: expose machine-readable `state` enums and failure categories; prefer bulk initialization/status RPCs over repeated per-entity polling when clients need initial state.

Example pattern (server response shape):
```rust
// Instead of: ReadFilesResult::Success { files: vec![] }
// Use something like:
ReadFilesResult::Success {
  files: vec![/* successfully read files */],
  missing_ranges: vec![
    MissingRange { path: "a.txt", line_range: (1891, 2090) }
  ],
}

// Or, if per-file success is granular:
ReadFilesResult::Success {
  per_file: vec![
    PerFileResult::Ok { path: "a.txt", segments: vec![...] },
    PerFileResult::MissingRange { path: "b.txt", requested: (1891, 2090), eof: 1237 },
  ]
}
```

This keeps the API truthful, prevents misleading UI states, and lets agent/client logic “course-correct” without breaking the ability to return other successfully retrieved items.

---

## Robust config handling

<!-- source: warpdotdev/warp | topic: Configurations | language: Markdown | updated: 2026-05-02 -->

Treat configuration as a stable, privacy-safe contract: it must load without breaking the whole file, resolve safely at apply-time, use platform-correct paths, and (for significant changes) be shipped behind feature flags with explicitly defined non-lossy toggle behavior.

Apply these rules when you change or add configuration, settings, or config-driven behavior:

1) Prefer Settings persistence over ephemeral UI
- If a user option must apply across multiple surfaces (panels, embedded views, etc.), store it in Settings (or a persisted setting), not only as a toolbar-only toggle.

2) Feature-flag major behavior changes
- Gate substantial features behind a named flag.
- Define defaults per channel (e.g., stable off, dev/preview on).
- Ensure flag-off behavior is non-lossy: persisted state remains on disk, and rendering/apply-time application changes are well-defined.
- Add integration tests that verify round-trip behavior when flipping the flag.

3) Make config parsing fail-soft; validate at apply-time
- Do not make “unknown theme/name/value” fail entire YAML/TOML loads.
- Use types like `Option<String>` for free-form references at the schema layer, then resolve into canonical internal types during application.
- When a value is unknown, log a warning once per load/apply and fall through to the next resolution layer for that entry only.

4) Resolve paths centrally and pass resolved values
- Never require downstream components/agents to guess locations like `~/.warp*/`.
- Use the project’s path helpers to compute the correct config directory/file path for the current OS (and ensure it’s reachable in test builds).
- Prefer embedding the resolved path in templated contexts over instructions to infer it.

5) Treat sensitive config data as local-only; redact diagnostics
- If configuration keys/values can encode sensitive user/project/org context, set sync off (local/private) and avoid including raw paths/keys in logs.
- Use stable redacted identifiers (hashes) for warnings so users can correlate repeated messages without leaking raw data.

6) Keep bundled/agent-exposed skills aligned with the schema
- If your config schema adds an option (e.g., `working_directory`), update the bundled skill so it explains defaults and supports the override parameter with correct example structure.

Example pattern (fail-soft + apply-time resolution + safe warning):
```rust
// Schema layer: never fails load on unknown values
#[derive(Deserialize)]
struct Entry { theme_ref: Option<String> }

// Apply-time resolution (per-entry fallback)
fn apply_entry(entry: Entry) {
    if let Some(raw) = entry.theme_ref {
        match resolve_theme_ref(&raw) {
            Some(theme) => set_effective_theme(theme),
            None => {
                let id = redacted_key_id(&raw); // or for the config key
                log::warn!("config[hash={}] unknown theme '{}'; skipping entry", id, raw);
                // fall through to next resolution layer
            }
        }
    }
}
```

Use this standard as a checklist during reviews for anything under the “Configurations” umbrella: settings schema changes, feature-flag rollout wiring, config-driven rendering/application, path handling, and privacy/sync behavior.

---

## Canonical Naming Sources

<!-- source: warpdotdev/warp | topic: Naming Conventions | language: Markdown | updated: 2026-04-29 -->

Use canonical, source-verified naming for identifiers and for artifact locations. Avoid guesses, stale references, or incidental structure (like username folders).

Apply:
- **Action/UI names and shortcuts in docs**: Only reference action IDs and default bindings that are confirmed against the source of truth. If the correct name can’t be discovered from disk, don’t invent one—either direct users to the correct settings page for lookup or require explicit confirmation.
- **Spec/artifact file placement**: Place specs in the prescribed directory scheme based on the **linear ticket id** (not usernames or ad-hoc nesting).

Example (action naming rule):
- Good: point users to the actual editor action (e.g., `workspace:show_keybinding_settings`) rather than a similarly named page action.
- Bad: reference `cmd-k` / `workspace:toggle_keybindings_page` if source verification shows the canonical editor shortcut/action is different.

Example (path naming rule):
- Good: `specs/<linear-ticket-id>/...`.
- Bad: `specs/<username>/<linear-ticket-id>/...` or any structure that doesn’t match the ticket-id convention.

---

## Optional Fallback Discipline

<!-- source: warpdotdev/warp | topic: Null Handling | language: Markdown | updated: 2026-04-29 -->

When working with nullable/optional values or external/runtime-provided fields, never assume presence or a specific concrete type/spelling. Instead: (1) explicitly treat inputs as optional, (2) provide deterministic fallbacks (often empty string/None/previous-state), (3) avoid dereferencing missing values, and (4) add tests for both “value present” and “value absent / alternate field present” cases.

Apply this especially to:
- UI state: preserve the existing focus target if one exists (it may not be terminal input); don’t hardcode a single focus type.
- Runtime metadata/env fields: probe multiple possible field names across versions and fall back safely when neither exists.
- Generated values: when a field is unavailable, emit a safe inert default (e.g., `""`) rather than constructing partial commands/paths.

Example (runtime field fallback):
```rust
fn nu_home_path(env: &HashMap<String, String>) -> String {
    // Prefer $nu.home-path when exposed; fall back to $nu.home-dir, then finally $HOME.
    env.get("nu.home-path")
        .or_else(|| env.get("nu.home-dir"))
        .or_else(|| env.get("HOME"))
        .cloned()
        .unwrap_or_else(|| "".to_string())
}
```

Checklist for PRs:
- Are any runtime/API/UI-derived values optional? If yes, are they handled with fallbacks (not assumptions)?
- Are there tests that cover absence and alternate-field spelling/runtime versions?
- Does the code avoid “half-built” outputs when values are missing (e.g., empty string/inert output instead of null or malformed command text)?

---

## Use Sudo Helper

<!-- source: warpdotdev/warp | topic: Security | language: Other | updated: 2026-04-29 -->

When writing shell scripts that run privileged operations, never call `sudo` directly or execute such commands silently. Centralize privilege escalation in a helper that (1) prints the exact command being run, (2) prompts for confirmation by default, and (3) provides an explicit, documented non-interactive escape hatch for CI (e.g., an env var like `WARP_BOOTSTRAP_YES=1` or auto-skip when stdin isn’t a TTY).

Example (bash):
```bash
#!/usr/bin/env bash
set -euo pipefail

warp_sudo() {
  local cmd=("$@")
  echo "About to run as sudo: ${cmd[*]}"

  if [[ "${WARP_BOOTSTRAP_YES:-false}" == "true" ]] || [[ ! -t 0 ]]; then
    sudo "${cmd[@]}"
    return
  fi

  read -r -p "Proceed? [y/N] " ans
  case "${ans}" in
    y|Y) sudo "${cmd[@]}" ;;
    *) echo "Aborted."; return 1 ;;
  esac
}

# Use the helper instead of direct sudo:
# warp_sudo brew install jq
# warp_sudo apt-get update
```

Apply this standard anywhere your scripts install system-wide packages, modify system configuration, or otherwise require super-user privileges.

---

## CI/CD release hygiene

<!-- source: mermaid-js/mermaid | topic: CI/CD | language: Json | updated: 2026-03-26 -->

For any PR that affects the build/release pipeline (scripts, manifests like package.json, or release tooling), require:

1) Pipeline must be green before requesting/continuing review
- No unexpected changes to root package manifests or release inputs unless necessary.

2) Release automation must be complete and consistent
- Include a changeset for versioned releases.
- Ensure the changeset bump type matches the intended semver outcome (don’t rely on implicit mapping).
- Include corresponding docs/changelog updates when required by the project process.

3) Local quality gates must mirror CI (or be clearly split)
- Avoid having `pnpm lint` behave differently from what CI runs.
- If you need faster local feedback, introduce explicit targets and make the default match CI.

Example script structure (align local with CI, while still allowing fast runs):
```json
{
  "scripts": {
    "lint:fast": "pnpm biome check && pnpm lint:jison",
    "lint:fast:fix": "pnpm biome check --write",
    "lint:slow": "pnpm lint:fast && cross-env NODE_OPTIONS=--max_old_space_size=16384 eslint --cache --cache-strategy content .",
    "lint": "pnpm lint:slow",
    "lint:fix": "pnpm lint:fast:fix && cross-env NODE_OPTIONS=--max_old_space_size=8192 eslint --cache --cache-strategy content --fix . && tsx scripts/fixCSpell.ts"
  }
}
```
Also update any CI workflow or automation that calls the old script names so CI and local stay in sync.

Practical checklist before merge:
- CI passes.
- package.json changes are intentional.
- changeset exists and semver intent is correct.
- required docs/changelog updates are included.
- `pnpm lint` (and other gated commands) reflect what CI enforces, or the split is explicit and workflow references are updated.

---

## Consistent Naming Rules

<!-- source: mermaid-js/mermaid | topic: Naming Conventions | language: TypeScript | updated: 2026-03-17 -->

Adopt consistent, explicit identifier naming across diagrams and TypeScript APIs.

**Rules**
1) **Diagram ids/syntax keywords**
- Use **lower-case** diagram identifiers.
- For **new/unstable syntax**, append **`-beta`** to the syntax/keyword the parser accepts.
- Keep semantic parts of names **uniform** (don’t introduce ad-hoc prefixes like `Mini` or extra suffixes like `Language` unless the codebase has a single established pattern).

2) **TypeScript naming style**
- **Types**: use **UpperCamelCase** (e.g., `DiagramStylesProvider`).
- **Interfaces**: prefer `interface` for object shapes when possible.

3) **Type-only files**
- Avoid using `.d.ts` for internal project types.
- Use a dedicated convention like **`.type.ts`** (e.g., `gantt.type.ts`).

4) **Exported fields/props**
- Prefer **explicit names** for public types (e.g., `width`/`height` over `w`/`h`) to improve readability for downstream users.

5) **Stability/compatibility for naming formats**
- If an identifier format is consumed externally (e.g., edge id strings), treat it as a contract: don’t rename/separator-change without an explicit compatibility plan.

**Example**
```ts
// diagram detector keyword
const detector: DiagramDetector = (txt) => /^\s*contextMap-beta/.test(txt);

// stable diagram config key naming: one established pattern
export interface MermaidConfig {
  contextMap?: MiniContextMapLanguageDiagramConfig; // avoid “Mini…Language…” unless consistent everywhere
}

// type-only file convention
// packages/mermaid/src/diagrams/gantt/gantt.type.ts
export type DiagramStylesProvider = (options?: Record<string, unknown>) => string;

// explicit fields
export interface NodeMetaData {
  width?: string;
  height?: string;
}
```

---

## Prefer Grammar Over Regex

<!-- source: mermaid-js/mermaid | topic: Algorithms | language: TypeScript | updated: 2026-03-17 -->

Use the language parser/grammar (e.g., Langium/Jison) for diagram syntax instead of hand-rolled regex parsing. Regex is allowed only for small, well-bounded token-level helpers when (a) it precisely matches the intended grammar slice (e.g., remove only *outer* quotes), (b) it doesn’t destructively change user content or semantics, and (c) it preserves source positions/ranges by avoiding pre-processing that removes/reflows lines before parsing.

Apply these rules:
- **No “core syntax” regex parsing**: if parsing needs to understand quoting, delimiters, comments/directives, or multi-token constructs, implement it in the `.langium` / grammar layer.
- **No destructive transforms**: transformations like stripping wrappers must not remove inner quotes/apostrophes.
- **Parser-owned comment/directive handling**: handle `%% ...` comments and directives in the parser so AST line/range data stays accurate.
- **Delimiter ownership is explicit**: commas/other delimiters should be represented in grammar structure; avoid regexes that “capture beyond” node/value boundaries.

Example: wrapper-quote removal must be outer-only (not global):
```ts
function stripOuterQuotes(s: string): string {
  const t = s.trim();
  if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
    // remove only the outer quotes
    return t.slice(1, -1);
  }
  return t;
}
```

When you must match with regex (e.g., token-level extraction), keep it narrowly scoped and back it with tests for edge cases (escaped quotes, whitespace variations, delimiter presence, comments).

---

## Changeset release hygiene

<!-- source: mermaid-js/mermaid | topic: CI/CD | language: Markdown | updated: 2026-01-29 -->

Ensure changeset PRs produce correct and minimal release automation output.

Apply these rules before submitting:
- **Create changesets only for user/release-relevant changes.** If it’s documentation-only, **do not** add a changeset.
- **Scope packages precisely.** A changeset header should include **only the packages that are actually affected**.
- **Split multi-package changes when entries should land in separate release notes.** If one change affects two packages independently, use **separate changeset files** rather than combining messages in one.
- **Choose the semver level based on user impact:**
  - **`major`**: reserved for **breaking changes**.
  - **`patch`**: bug fixes / no user-facing behavior change.
  - **`minor`**: non-breaking new functionality/improvements that affect users.
  - Avoid using non-standard bump labels (e.g., `chore`) when `major/minor/patch` is expected.

Example (correct semver selection + scoped header):
```md
---
'mermaid': patch
---
fix: Correct diagram rendering regression
```

Example (split multi-package change into separate files):
- File A: bump only `@mermaid-js/examples`
- File B: bump only `mermaid`
with each file containing only its relevant release-note text and semver decision.

---

## Comprehensive Test Coverage

<!-- source: mermaid-js/mermaid | topic: Testing | language: Markdown | updated: 2026-01-29 -->

When implementing or extending functionality, ensure tests (primarily unit tests for non-renderer code) cover the full supported behavior surface—not just a subset.

Apply this as:
- For new/expanded supported inputs (e.g., HTML tags), add test cases for every supported variant.
- Keep unit tests mandatory for all non-renderer code; use integration tests for renderers.

Example pattern (unit-test style):
```js
const supportedTags = ['em','strong','sup','a','ul','li'];

describe('timeline label HTML support', () => {
  supportedTags.forEach((tag) => {
    it(`renders timeline label with <${tag}>`, () => {
      const input = `Label with <${tag}>text</${tag}>`;
      const output = renderTimelineLabel(input); // your unit-level function
      expect(output).toContainTag(tag); // adapt to your assertion style
    });
  });
});
```

This standard prevents partial coverage (only testing `<br>`/`<strong>`) and ensures consistent test expectations across the codebase.

---

## Document API Changes

<!-- source: mermaid-js/mermaid | topic: Documentation | language: JavaScript | updated: 2026-01-16 -->

When you change an exported/non-trivial API (or add new function parameters), update JSDoc so it is complete and directly helpful:

- For every added/changed parameter: include a `{type}` and a short description of what the parameter controls.
- For deprecations: use `@deprecated` and point to the replacement using a link (e.g., `{@link NewSymbol}`), not just plain text.

Example (parameter documentation)
```js
/**
 * @param {any} node
 * @param {number} [width] - Max/target label width used for wrapping calculations.
 * @param {boolean} [addBackground=false] - Whether to apply the label background styling.
 * @returns {Promise<SVGForeignObjectElement>}
 */
async function addHtmlLabel(node, width, addBackground = false) {
  // ...
}
```

Example (deprecation documentation)
```js
/**
 * @deprecated Use {@link getBoundaries} instead
 */
export const getBoundarys = getBoundaries;
```

---

## Config-driven theming

<!-- source: mermaid-js/mermaid | topic: Configurations | language: JavaScript | updated: 2026-01-15 -->

When rendering/layout is affected by configuration or theming, avoid magic numbers and ad-hoc config handling. Instead:

- Use a centralized “effective config” helper for all config-derived decisions, including correct type coercion (e.g., treat `"false"` the same as `false`).
- Derive theme-/appearance-sensitive values from `themeVariables` (or CSS vars like `--mermaid-font-family`) rather than hard-coding constants that break with different fonts/sizes.
- Apply theming values consistently across SVG/CSS/labels so users can rely on a single source of truth.
- If changing defaults would cause visual regressions, preserve existing behavior in the default path and gate improvements behind theme/config changes.

Example pattern:
```js
// config.js
export function getEffectiveFlowchartHtmlLabels(siteConfig) {
  // Correctly coerce string booleans
  const v = siteConfig?.flowchart?.htmlLabels;
  return v === true || v === 'true';
}
```
And for theme-derived styling:
```js
// instead of spacing = 60; or font-family: ${options.fontFamily};
const spacing = themeVariables?.noteSpacing ?? 60; // or derive from other theme vars
const fontFamily = 'var(--mermaid-font-family), trebuchet ms, verdana, arial, sans-serif';
```

---

## Precise Scenario-Based Testing

<!-- source: mermaid-js/mermaid | topic: Testing | language: TypeScript | updated: 2026-01-08 -->

When writing tests, ensure they (1) match the scenario name and input data, (2) exercise behavior through the appropriate layer (prefer public/high-level APIs so defaults/precedence are covered), (3) use the project’s DOM test helpers/fixtures and avoid unnecessary mocks/polyfills, and (4) assert specific outcomes (including exact error messages) rather than broad behaviors.

Apply it like this:
- **Scenario alignment:** Don’t reuse the same input across multiple cases if each test’s name implies different behavior (short/medium/long, enabled/disabled, etc.).
- **Right layer:** If a behavior depends on configuration precedence/defaulting, validate through the same API path production uses (e.g., config APIs), not by indirectly testing internal functions unless there’s no public entrypoint.
- **Mock minimization:** Keep only mocks that the environment truly can’t support; if `jsdomIt` can provide a real DOM, prefer it over spies/mocked D3/cytoscape.
- **Specific assertions:**
  - For failures, assert the **actual error message**.
  - For object identity tests, also assert meaningful fields/types/values when relevant.
- **Maintainability:** Prefer inline snapshots and simpler setup; remove redundant initialization calls when the test doesn’t require them.

Example (DOM test with fixture + specific assertions):
```ts
import { expect } from 'vitest';
import { jsdomIt } from '../test-utils/jsdomIt';
import { select } from 'd3-selection';
import { addSVGa11yTitleDescription } from './a11y';

jsdomIt('does not insert title tag', ({ svg }) => {
  const svgSelection = select<SVGSVGElement, never>(svg);

  addSVGa11yTitleDescription(svgSelection, 'chart-title', undefined, 'givenId');

  const titleNode = svg.querySelector('title');
  expect(titleNode).toBeNull();
});
```

Example (error message assertion):
```ts
await expect(renderSomething(badInput)).rejects.toThrow(
  'Expected exact error message here'
);
```

This combination prevents “false green” tests, improves coverage, reduces brittle mocks, and makes regressions easier to diagnose.

---

## Doc Examples Must Render

<!-- source: mermaid-js/mermaid | topic: Documentation | language: Markdown | updated: 2026-01-08 -->

All documentation examples/configs must be compatible with the docs build/render pipeline and current Mermaid configuration conventions.

**Apply this checklist when touching documentation:**
- **Use the current config mechanism**: prefer YAML/frontmatter (and `themeVariables`) over deprecated `%%{init: ...}%%` in examples.
- **Version-gate features** in docs using `(v<MERMAID_RELEASE_VERSION>+)` (or the project’s equivalent placeholder) when the behavior is version-dependent.
- **Never duplicate render blocks**: if the docs tooling auto-renders `mermaid-example`, include **one** block—don’t add multiple identical code fences.
- **Keep code fences and syntax valid for the renderer** (no extra punctuation/backticks that would prevent rendering).
- **Prefer Mermaid-supported formatting** for diagram text (avoid relying on Markdown-only behavior when Mermaid parsing expects different line-break semantics).
- **Use relative internal links** in source docs (so site link rewriting works).

**Example (correct: frontmatter + single mermaid-example + version tag):**
```md
```mermaid-example
---
title: ELK layout example
config:
  layout: elk
---
erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE-ITEM : contains
```
```

**Example (avoid):**
- Using `%%{init: ...}%%` when examples have been migrated to YAML/frontmatter.
- Copy-pasting the same `mermaid-example` block twice (final docs will render duplicates).

---

## Config must be consistent

<!-- source: mermaid-js/mermaid | topic: Configurations | language: TypeScript | updated: 2026-01-08 -->

Ensure every rendering/utility path uses the correct configuration *namespace* and that config values are passed explicitly (not implicitly via global getters or captured/stale variables).

Practical rules:
- **Match config paths end-to-end**: if tests set `config.flowchart.htmlLabels`, the code that affects label sizing must read the same path (and the same key name).
- **Don’t pull config inside internal helpers**: prefer passing `config`/needed flags as parameters so helpers are deterministic and easy to test.
- **Avoid caching/stale config snapshots**: don’t compute `const conf = getConfig().<section>` once if it can be initialized later; fetch/use config at the correct lifecycle or keep the prior approach.
- **Use diagram-specific defaults**: when computing defaults for a diagram/module, read from its own config section (e.g., block defaults from `config.block`, not `config.flowchart`).

Example pattern (config injection):
```ts
// Bad: internal utility reaches out to global config
import { getConfig } from '../config.js';
function preprocessMarkdown(markdown: string) {
  const markdownAutoWrap = getConfig().markdownAutoWrap;
  // ...
}

// Good: pass only what you need
function preprocessMarkdown(markdown: string, markdownAutoWrap: boolean) {
  // ...
}

// Call site
const { markdownAutoWrap } = getConfig();
preprocessMarkdown(markdown, markdownAutoWrap);
```

---

## Explicit Null Handling

<!-- source: mermaid-js/mermaid | topic: Null Handling | language: TypeScript | updated: 2026-01-08 -->

Null/undefined safety should prevent crashes *and* preserve correct semantics. Don’t hide missing required inputs with optional chaining or weak fallbacks.

**Standards**
1. **Validate required dependencies explicitly**: If an object (e.g., `themeVariables`) is expected to exist, check it and emit a warning/error when it’s missing instead of silently continuing.
2. **Use type-correct defaults, not `null` sentinels**: If downstream code expects a color/string/number/boolean, provide a real default of that type—avoid `?? null` unless the API explicitly supports `null`.
3. **Avoid truthiness logic that changes meaning**: Watch for patterns like `value || true` (it always becomes `true`). Compute booleans with correct precedence.
4. **Be intentional about `null` vs `undefined`**: Use `??` when you only want to treat `null/undefined` as “missing”, and add explicit branches when precedence matters.

**Example pattern**
```ts
function getThemeValue<T>(theme: any, key: string, fallback: T): T {
  if (!theme) {
    console.warn(`Missing themeVariables; using fallback for ${key}`);
    return fallback;
  }
  const value = theme[key];
  if (value === undefined || value === null) {
    console.warn(`Missing theme value ${key}; using fallback`);
    return fallback;
  }
  return value as T;
}

const quadrant1Fill = getThemeValue(themeVariables, 'quadrant1Fill', '#000000');

// Boolean example: avoid `anything || true`
const useHtmlLabels = node.useHtmlLabels ?? evaluate(config.htmlLabels ?? undefined) ?? true;
```

Applying these rules makes UI/config failures easier to diagnose, avoids runtime surprises from invalid sentinel values, and keeps boolean/null semantics correct.

---

## Null-safe Input Contracts

<!-- source: mermaid-js/mermaid | topic: Null Handling | language: JavaScript | updated: 2026-01-08 -->

When handling possibly-null/undefined/empty inputs, be explicit about nullability and keep code aligned with the promised types/semantics.

Practical rules:
- Guard early for empty strings / missing values: return immediately instead of continuing with invalid state.
- Prefer nullish coalescing (`??`) over falsy checks (`||`) when `false` (or `0`) is a valid value that must not be treated as “missing”.
- Ensure return types and JSDoc contracts match reality (don’t return `undefined` when the function claims `string`).
- Before arithmetic/formatting, normalize union-like values (e.g., `number | string`) via a shared parser or an explicit `typeof` check.
- Don’t paper over typing issues caused by `null` defaults; add/propagate types so nullability doesn’t collapse inference.

Example pattern:
```js
function getStylesFromDbInfo(dbInfoItem) {
  return dbInfoItem?.styles ?? ''; // always a string
}

function useHtmlLabels(node, config) {
  // preserves false when it matters; only falls back on null/undefined
  return node.useHtmlLabels ?? config.flowchart.htmlLabels;
}

function getTasks(rawTasks, dateRange) {
  if (dateRange === '') return rawTasks; // early return on empty input

  // parse defensively
  const [startStr, endStr] = dateRange.split(',');
  // only use pieces if present
}
```

This reduces null/reference bugs and prevents subtle behavior changes caused by incorrect falsy-vs-nullish handling or mismatched return contracts.

---

## Versioned API Change Contracts

<!-- source: mermaid-js/mermaid | topic: API | language: Markdown | updated: 2026-01-08 -->

When changing a user-facing interface (API/config/grammar or externally consumed resources), treat it as a versioned contract:

1) Classify change severity and reflect it in release artifacts
- For deprecations: include the “why” (what/which user scenarios are impacted) and what the supported alternative is.
- If you also ship compatibility work (e.g., supporting the new config “whenever possible”), add a separate fix/patch-level entry rather than burying it in the deprecation note.

2) Isolate breaking changes from releases you can’t roll back
- If behavior/grammar is breaking, do not ship additional new syntax in the same release unless you have an explicit, reversible plan.
- Prefer shipping only the currently agreed compatibility surface, and track additional syntax separately.

3) Explicitly version external interface/resource URLs
- For CDN/external loaders used by clients, include a major version (or equivalent) in the URL so updates don’t silently change runtime behavior.

Example patterns:
- Changeset structure (deprecation + patch/fix):
```md
---
'my-feature': patch
---
fix: Support the `htmlLabels` config value whenever possible

---
'my-feature': minor
---
feat: Deprecate `flowchart.htmlLabels` in favor of root-level `htmlLabels`
```
- Staged syntax release (don’t mix breaking syntax):
```text
Release N: ship only `@{ ... }` syntax (no additional simplified grammar)
Release N+1: add simplified syntax under separate ticket/version
```
- Versioned CDN URL:
```js
// Prefer an URL that includes a major version segment
fetch('https://cdn.example.com/mermaid@3/icons/icons.json')
```

Apply this standard to ensure clients get predictable behavior, deprecations are actionable (not vague), and breakage risk is contained through semantic change classification and explicit versioning.

---

## Prefer fast-paths and caching

<!-- source: mermaid-js/mermaid | topic: Performance Optimization | language: TypeScript | updated: 2026-01-07 -->

When performance matters, structure code to avoid unnecessary work: (1) keep cheap fast-paths first for short-circuiting, (2) cache expensive global lookups (like config) instead of repeatedly calling them, (3) reuse costly parser/services/stateful objects, (4) lazy-load heavy dependencies only when required, and (5) remove redundant rendering/computation that increases output size.

Practical rules:
- Short-circuit with the most likely/cheapest override first.
  ```ts
  // Fast path: user/node override avoids config evaluation
  const useHtmlLabels = node.useHtmlLabels || getEffectiveHtmlLabels(getConfig());
  ```
- Cache `getConfig()` once per function scope.
  ```ts
  const config = getConfig();
  const titleColor = config.themeVariables.titleColor;
  ```
- Don’t recreate expensive parsers/services per call; initialize once and reuse.
- Lazy-import heavy modules only when needed (and ideally only when the input contains the relevant markers).
  ```ts
  if (needsMathML && hasKatex(text)) {
    const katex = await import('katex');
    // ...use katex
  }
  ```
- Avoid generating unnecessary DOM/SVG output; remove recursive logic that “shaves” nothing visually but adds many elements.

These changes reduce CPU time, allocations, and network/module load, improving both runtime responsiveness and load time.

---

## Short-circuit and cache

<!-- source: mermaid-js/mermaid | topic: Performance Optimization | language: JavaScript | updated: 2026-01-07 -->

Optimize performance-sensitive code by eliminating unnecessary work:

- **Short-circuit expensive calls:** order conditions so cheap checks run first and prevent calling costly functions.
  ```js
  // Prefer cheap value first to avoid extra computation
  const useHtmlLabels = node.useHtmlLabels || getEffectiveHtmlLabels(getConfig());
  ```

- **Cache invariants outside loops:** don’t call configuration/derived getters repeatedly inside `forEach`/`map`/render loops.
  ```js
  const config = getConfig();
  data.nodes.forEach((item) => {
    // use cached config
  });
  ```

- **Centralize heavy transformations & consider lazy loading:** if you add expensive rendering (e.g., KaTeX/FontAwesome label processing), move shared logic into a common utility used by all diagrams, and consider async/lazy loading so the heavy dependency isn’t bundled/initialized for all cases.
  ```js
  // Idea: shared label transform + optional lazy import of heavy lib
  export async function renderMathLabels(input) {
    const { katex } = await import('katex');
    return katex.renderToString(/*...*/);
  }
  ```

---

## Consistent Style And Diffs

<!-- source: mermaid-js/mermaid | topic: Code Style | language: JavaScript | updated: 2026-01-05 -->

Apply a consistent, tool-friendly coding style to reduce formatting churn and improve readability.

**Rules**
- **Keep diffs stable:** Don’t apply formatting-only changes to existing tests/cases unless the PR’s purpose is explicitly formatting coverage. Revert incidental alignment/whitespace changes; add new focused cases instead.
- **Respect formatter/tool expectations:** e.g., avoid adding/removing whitespace in import groups if your tooling depends on it.
- **String/concatenation consistency:** build class/name strings consistently (no mixed whitespace prefixes like ` ' ' + a` sometimes vs `a + ' '` other times). Prefer a single consistent pattern.
- **Use clearer JS constructs:**
  - Prefer **template literals/backticks** for readability when composing multi-line strings or larger literals.
  - Use **`===` / `!==`** everywhere (avoid `==`).
  - Prefer **early returns** to simplify nested conditionals.
  - Avoid **magic numbers** in new code; use named constants if values affect layout/logic.

**Example (test string readability + stable diffs)**
```js
it('should parse bidirectional arrow', async () => {
  const str = `sequenceDiagram\nAlice-><Bob:Hello Bob, how are you?`;
  await mermaidAPI.parse(str);
  const messages = diagram.db.getMessages();
  expect(messages).toHaveLength(1);
});
```

**Example (avoid magic numbers)**
```js
const TODAY_LINE_WIDTH = 30;
line.attr('y2', conf.titleTopMargin + TODAY_LINE_WIDTH);
```

Use this checklist when preparing commits: if a change is purely formatting, isolate it (or revert it) and keep PR intent behavior-focused.

---

## Include context-rich logs

<!-- source: wavetermdev/waveterm | topic: Logging | language: Go | updated: 2026-01-04 -->

Ensure logs are actionable: always include relevant context identifiers (e.g., full connection name, user or request id) and log any returned errors so failures are visible and debuggable. Mask or redact sensitive fields when necessary and choose an appropriate log level (info for status changes, warn/error for failures).

How to apply:
- Add identifying context to messages that describe operations or failures so developers and users can trace what happened. Example: include conn.GetName() in connect errors.
- Always capture and log errors returned from helpers and background goroutines instead of ignoring them.
- If a value could be sensitive or overly verbose, mask or redact the sensitive portion before logging.
- Prefer structured logging where available (fields for name, id, error) to aid searching and aggregation.

Code examples (pattern to follow):

// include full connection name and log error
if err := conn.Connect(ctx, connFlags); err != nil {
    // show identifying context and the error
    log.Printf("error connecting to %q (status=%q): %v", conn.GetName(), conn.GetStatus(), err)
    return fmt.Errorf("cannot connect to %q when status is %q: %w", conn.GetName(), conn.GetStatus(), err)
}

// always log helper errors and goroutine results
err := setNoReleaseCheck(ctx, clientData, false)
if err != nil {
    log.Printf("failed updating client no-release-check for client=%q: %v", clientData.ClientID, err)
    return err
}

go func() {
    if err := releasechecker.CheckNewRelease(false); err != nil {
        log.Printf("background release check failed: %v", err)
    }
}()

Notes:
- Use appropriate log levels (error/warn/info) and structured fields where possible.
- Redact sensitive values (tokens, passwords) before logging; prefer logging stable identifiers (ids, names) instead of secrets.
- Logging errors promptly (including from goroutines) prevents silent failures and improves operability.

---

## Avoid Duplication Magic

<!-- source: mermaid-js/mermaid | topic: Code Style | language: TypeScript | updated: 2026-01-02 -->

When updating code, prioritize maintainability and readability by removing duplicated blocks, eliminating magic numbers, and keeping formatting/imports tooling-friendly.

Apply these rules:
- DRY duplicated logic: if the same algorithm/parameter set is repeated (e.g., measuring, wrapping, then shrinking/redrawing), extract it into a single helper/variable so future changes happen in one place.
- Remove magic numbers: replace unexplained numeric literals with named constants (ideally sourced from existing config/theme). This makes intent clear and prevents silent breakage if related limits change.
- Improve readability: use template literals instead of string concatenation where it clarifies intent, and keep import grouping consistent so auto-import tools don’t mis-group files.

Example (extract repeated wrap/shrink into one function):
```ts
const MAX_AVAILABLE_WIDTH = pieWidth - MARGIN;
const START_FONT_SIZE = 25;
const MIN_FONT_SIZE = 8;

function renderWrappedTitle(svg: any, titleText: string) {
  let fontSize = START_FONT_SIZE;
  let wrapped = wrapLabel(titleText, MAX_AVAILABLE_WIDTH, {
    fontSize,
    fontFamily: 'Arial',
    fontWeight: 400,
    joinWith: '<br/>',
  });

  // measure once per fontSize change
  let tempTitle = svg.append('text')
    .attr('x', pieWidth / 2)
    .attr('y', 30)
    .attr('class', 'pieTitleText')
    .style('text-anchor', 'middle')
    .style('white-space', 'pre-line')
    .style('font-size', fontSize + 'px');

  while (tempTitle.node()?.getBBox().width > MAX_AVAILABLE_WIDTH && fontSize > MIN_FONT_SIZE) {
    tempTitle.remove();
    fontSize -= 1;
    wrapped = wrapLabel(titleText, MAX_AVAILABLE_WIDTH, {
      fontSize,
      fontFamily: 'Arial',
      fontWeight: 400,
      joinWith: '<br/>',
    });

    tempTitle = svg.append('text')
      .attr('x', pieWidth / 2)
      .attr('y', 30)
      .attr('class', 'pieTitleText')
      .style('text-anchor', 'middle')
      .style('white-space', 'pre-line')
      .style('font-size', `${fontSize}px`);
  }

  const lines = wrapped.split('<br/>');
  lines.forEach((line, idx) => {
    tempTitle.append('tspan')
      .attr('x', pieWidth / 2)
      .attr('dy', idx === 0 ? 0 : '1.2em')
      .text(line);
  });

  return tempTitle;
}
```

Following this standard reduces duplicated maintenance work, makes “why” obvious (constants), and keeps code easier to review and debug.

---

## Use supported documentation formats

<!-- source: mermaid-js/mermaid | topic: Documentation | language: TypeScript | updated: 2025-12-17 -->

When updating documentation, examples, or config-related code:

1) Follow the source of truth for generated artifacts
- **Do** change the upstream schema/config file.
- **Don’t** edit generated files directly.

2) Use the supported frontmatter format for diagram configuration
- **Do** use frontmatter (e.g., `---` block) to set config/theme.
- **Don’t** rely on deprecated directive init syntax like `%%{init: ...}%%` in tests/examples.

Example (frontmatter-style):
```md
---
title: Timeline example
theme: forest
config:
  logLevel: debug
---

timeline
  title Timeline Title
```

3) Prefer storing diagram sources in `.mmd` (or Markdown) for better developer ergonomics
- Keep an `index.ts` for metadata, and put each diagram in a corresponding `*.mmd` file for IDE syntax highlighting/plugins.

4) Avoid brittle Markdown “massaging”
- If you need indentation normalization, use a safe helper like `dedent()` instead of regex-based whitespace stripping (to prevent breaking lists and indented code blocks).

---

## Explicit API contracts

<!-- source: likec4/likec4 | topic: API | language: TypeScript | updated: 2025-12-06 -->

Require API types and public interfaces to express clear, enforceable contracts: guarantee invariants, normalize variant shapes, and make compatibility choices explicit.

Why: Clear types prevent subtle bugs, make callers’ expectations explicit, and make evolving an API safer (clients can rely on invariants or intentionally opt into legacy shapes).

How to apply (practical rules):
- Prefer precise return types that guarantee required fields instead of vague or permissive types. If a function promises to return a node with a specific model FQN, express that in the signature.
  Example:
  function findNodeByModelFqn<T extends NodeWithData>(
    nodes: Types.Node[],
    modelFqn: Fqn
  ): (Types.Node & { data: { modelFqn: Fqn } }) | null

- When two fields are conceptually paired, represent them as a single array of paired objects so their relationship and lengths are guaranteed:
  // instead of separate includePaths?: URI[] and includePathsAsStrings?: ProjectFolder[]
  includePaths?: Array<{ uri: URI, folder: ProjectFolder }>

- Normalize variant/union shapes using discriminants and common base types; provide parsing/mapping helpers that convert legacy or multiple AST/kinds into a single canonical representation. When you must keep legacy shapes, add an explicit flag or an optional legacy field rather than implicit differences:
  type DynamicBranchCollectionBase = { branchId: string; astPath: string; kind: 'parallel' | 'alternate'; paths: DynamicBranchPath[] }
  interface DynamicParallelBranch extends DynamicBranchCollectionBase { kind: 'parallel'; isLegacyParallel?: boolean }

  Use small helpers to map input kinds to the normalized model:
  function getBranchKind(astKind: string): 'parallel' | 'alternate' {
    return astKind === 'alternate' || astKind === 'alt' ? 'alternate' : 'parallel'
  }

- Be explicit about semantic decisions that affect consumers (e.g., whether nested parallels are allowed or should be flattened). Either enforce the rule in the parser/validator or document/parameterize the behavior so callers/layout code can handle it deterministically.

Checklist for PR authors:
- Does each public function/type guarantee the required fields (no implicit assumptions)? If not, tighten the types.
- Are related arrays or fields paired as a single structure when their association matters? If not, refactor to a paired array/object.
- Are variant shapes represented by a canonical discriminated union? Is legacy behaviour explicit (flagged) and handled in parsing code?
- Have you documented any semantic choices that affect client behaviour (nesting rules, flattening policies)?

Applying these rules will make API boundaries explicit, reduce accidental breakage, and make evolution more controlled and predictable.

---

## Prefer utility reuse

<!-- source: likec4/likec4 | topic: Code Style | language: TypeScript | updated: 2025-12-06 -->

When changing or adding code prefer existing helpers, language-idiomatic constructs, and small well-maintained libraries to keep code DRY, readable, and consistent.

Why: Reusing helpers reduces duplication and bugs; using idiomatic patterns (entries, map, pipe) removes boilerplate and conditional checks; consistent literal formats improve readability; standard libraries avoid ad-hoc implementations for common tasks (e.g., color scales).

How to apply (checklist):
- Before adding logic, search for an existing helper or utility and reuse it. Example: replace manual find with an existing helper
  const node = findNodeByElementFqn(context.xynodes, elementFqn)
- Favor idiomatic JS/TS constructs over manual loops and guards. Example: prefer entries or functional pipelines to `for...in` plus manual checks
  for (const [id, styles] of entries(parsedGlobalRules.styles)) { /* ... */ }
  // or
  globalRules.styles = pipe(
    entries(parsedGlobalRules.styles),
    map(([id, style]) => ({ id, style })),
    indexBy(prop('id'))
  )
- Use consistent literal styles for readability: prefer triple-quoted multi-line strings for embedded markdown or long text blocks (match project conventions):
  notes: """
    # Title
    - bullet
  """
- Prefer well-maintained small libraries for common tasks rather than bespoke constants. Example: use @mantine/colors-generator (or an agreed color system like Radix/Open Colors) to produce consistent color scales rather than hand-picking values.

Guidance for code reviews:
- Ask whether new logic duplicates existing helpers; suggest reuse or extraction.
- Recommend idiomatic replacements for loops/conditionals when they simplify code and clarify intent.
- Enforce the project's chosen conventions for string literals and external libraries; prefer standard, vetted solutions for common domains (colors, formatting, parsing).

References: discussions 0, 1, 2, 3.

---

## Type-safe focused tests

<!-- source: likec4/likec4 | topic: Testing | language: TypeScript | updated: 2025-12-06 -->

Write tests that are both type-safe and narrowly focused on supported behavior. Use small, typed test helpers or fixtures to eliminate repeated casts and noisy "as any"/"as T" in tests, and ensure test cases reflect the product's validation rules (don’t test unsupported scenarios).

Why: Cleaner, safer tests are easier to read and maintain; helpers reduce boilerplate and prevent hiding type problems with casts. Keeping tests aligned with validation prevents brittle or misleading coverage.

How to apply:
- Add tiny helper functions or fixtures in test files that construct inputs with the correct shapes, so callers don't need to sprinkle type casts.
- Prefer positive tests that exercise only supported/valid cases. If a validation forbids a scenario (e.g., parent-child same-rank), don’t write a positive test that expects it to pass; instead write a negative test asserting the validation behavior.
- Keep test cases minimal — test one behavior per test and use helpers to reduce repetition.

Example helper (from discussion):

```ts
function testFindNodeByElementFqn(
  nodes: Array<{ id: string; data: { modelFqn?: string | null } }>,
  modelFqn: string
) {
  return findNodeByElementFqn(nodes as any, modelFqn as any)
}
```

Use it to remove casts in many tests and keep the test intent clear.

Example simplified rank test (only supported sibling case):

```ts
it('parses element view rank rules for siblings', async ({ expect }) => {
  const { parse, services } = createTestServices()
  const langiumDocument = await parse(`
    specification { element block }
    model {
      block root {
        block childA {}
        block childB {}
      }
    }
    views {
      view index {
        include *
        {rank=same; root childA childB}
      }
    }
  `)
  const doc = services.likec4.ModelParser.parse(langiumDocument)
  const ranks = doc.c4Views[0]!.rules.filter(rule => 'rank' in rule)
  expect(ranks).toHaveLength(1)
})
```

Checklist for PRs/tests:
- Add a helper when you find repeating casts or verbose mock construction.
- Confirm the test encodes supported behavior; if validation rejects a case, write a test asserting rejection instead of a positive success case.
- Keep tests small and readable; helpers should be local to the test file unless reusable across suites.

---

## Define Error Recovery Policy

<!-- source: mermaid-js/mermaid | topic: Error Handling | language: TypeScript | updated: 2025-12-03 -->

When handling failures, classify them as **recoverable** vs **unrecoverable**, then apply a consistent rule: log with enough context, **continue only for recoverable side-effects**, and **fail fast with explicit (prefer custom) errors** for invalid/unknown inputs or internal invariants.

Apply it like this:
- **Recoverable (graceful degradation):** wrap side-effect registration/optional subsystems so primary rendering still works.
- **Unrecoverable (fail fast):** unknown statement types, invalid style values, or malformed inputs should throw (don’t silently ignore).
- **Logging + propagation:** ensure default behavior remains consistent; config flags may change *how* you recover/cleanup, but should not accidentally swallow exceptions.

Example pattern (recoverable side-effect):
```ts
try {
  registerDiagramIconPacks(config.icons);
} catch (error) {
  log.error(
    'Failed to register icon packs, continuing with diagram render:',
    error,
  );
  // continue rendering
}
```

Example pattern (unrecoverable invalid input):
```ts
class InvalidStyleError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'InvalidStyleError';
  }
}

function parseRadius(value: string): number {
  if (!/^\d+$/.test(value)) {
    throw new InvalidStyleError(`radius value '${value}' must be a number`);
  }
  return parseInt(value, 10);
}
```

Example pattern (consistent propagation with suppression):
```ts
try {
  await diag.renderer.draw(text, id, version, diag);
} catch (e) {
  if (config.suppressErrorRendering) {
    removeTempElements();
  } else {
    errorRenderer.draw(text, id, version);
  }
  throw e;
}
```

---

## Clean CI configurations

<!-- source: nrwl/nx | topic: CI/CD | language: Yaml | updated: 2025-11-19 -->

Maintain clean and well-documented CI configurations by removing dead code and properly documenting temporary changes. Avoid leaving commented-out code in CI files - either remove unused configurations entirely or add proper TODO comments with context when temporarily disabling features.

When removing unused configurations, delete them completely rather than commenting them out. For temporary disabling due to issues, add TODO comments with explanations and follow-up plans.

Example:
```yaml
# Good - Clean removal
node_version:
  - 20
  - 22
  - 24

# Good - Temporary disable with context  
# TODO(v23): remove node 20 - EOL April 2026
# TODO: Re-enable Windows builds after fixing Gradle issue (assigned to @xiongemi)
# - os: windows-latest
#   node_version: 22

# Bad - Unexplained commented code
# - 23
```

This practice keeps CI configurations maintainable, reduces confusion for team members, and ensures temporary changes don't become permanent oversights.

---

## Avoid runtime API calls

<!-- source: nrwl/nx | topic: API | language: TSX | updated: 2025-11-17 -->

Components should not make external API calls for data that can be pre-generated at build time. Instead of fetching dynamic data during component rendering, inject pre-computed values as props to improve performance and reduce external dependencies.

When you have data that changes infrequently (like GitHub star counts, version numbers, or configuration data), fetch it during the build process and pass it into components rather than making runtime API calls.

Example of what to avoid:
```tsx
// ❌ Don't do this - runtime API call in component
useEffect(() => {
  const getStarCount = async () => {
    const response = await fetch('https://api.github.com/repos/nrwl/nx');
    const data = await response.json();
    setStarCount(data.stargazers_count);
  };
  getStarCount();
}, []);
```

Example of preferred approach:
```tsx
// ✅ Do this - pass pre-generated data as props
interface HeaderProps {
  starCount: number; // Fetched at build time
}

export function Header({ starCount }: HeaderProps) {
  return <span>{formatStarCount(starCount)}</span>;
}
```

This approach reduces client-side API calls, improves initial page load performance, and makes components more predictable and testable.

---

## validate configuration values

<!-- source: nrwl/nx | topic: Configurations | language: TypeScript | updated: 2025-11-14 -->

Always validate configuration values at runtime and provide clear, actionable error messages when invalid combinations are detected. This prevents runtime failures and guides users toward correct configuration.

Key validation practices:
- Check environment variables against allowed values before use
- Validate configuration combinations that are mutually incompatible  
- Provide specific error messages that explain the problem and suggest solutions
- Use runtime checks rather than relying on schema validation alone

Example from environment variable validation:
```typescript
if (
  !args.outputStyle && 
  process.env.NX_DEFAULT_OUTPUT_STYLE && 
  choices.includes(process.env.NX_DEFAULT_OUTPUT_STYLE as OutputStyle)
) {
  args.outputStyle = process.env.NX_DEFAULT_OUTPUT_STYLE;
}
```

Example from configuration combination validation:
```typescript
if (usesVersionPlaceholder && hasSkipVersionActions) {
  throw new Error(
    `Release group "${groupName}" configures "skipVersionActions" but its docker version scheme contains the "{versionActionsVersion}" placeholder which cannot be resolved without version actions. Remove "skipVersionActions" or remove the placeholder from the scheme.`
  );
}
```

This approach catches configuration errors early, provides clear guidance for resolution, and prevents confusing runtime failures that are difficult to debug.

---

## Deterministic Grammar Changes

<!-- source: mermaid-js/mermaid | topic: Algorithms | language: Other | updated: 2025-11-10 -->

When updating diagram parsers (Jison/Langium/Chevrotain), treat lexer/tokenization precedence as a compatibility contract: ensure changes don’t break existing inputs and that intended tokens are unambiguously chosen.

Apply these rules:
1) Assume the first/earliest matching token wins (Langium/Chevrotain behavior). Avoid overlapping regex/patterns that allow one token to “shadow” others. If overlap is unavoidable, control it explicitly (tighten patterns, reorder tokens, or use a custom matcher that refuses matches that should belong to other token types).
2) Never change the meaning of a previously-supported character/string without explicitly preserving the old interpretation (or providing a migration plan). If a symbol like `-` previously parsed as a generic/node string, keep that option working while adding the new operator token.
3) If you remove/replace lexer terminals to resolve conflicts, confirm that downstream validation preserves the same semantics the feature provided (don’t silently drop behavior).
4) Add regression tests for prior real-world diagrams/labels that previously worked—especially cases involving punctuation, quotes, and ambiguous terminals.

Example (conceptual fix for “shadowing”):
- Instead of defining a broad token that can match everything, define a narrower token or use a matcher that checks the input context before returning the token.

In code review, ask: “What token now matches this substring, and does that substring still parse the same way as before? Which token wins, and why?”

---

## User-centric documentation practices

<!-- source: nrwl/nx | topic: Documentation | language: Markdown | updated: 2025-11-06 -->

Documentation should prioritize user needs and experience over technical convenience. This means using appropriate link types (guides over API docs for user-facing content), organizing content to avoid overwhelming newcomers, providing necessary context, and ensuring links work correctly with tooling.

Key practices:
- Link to comprehensive guides rather than API documentation for user-facing scenarios: `/docs/technologies/testingtools/vitest/guides/migrating-from-nx-vite` instead of API docs
- Structure introductory content to be approachable - avoid leading with advanced technical concepts that might discourage users
- Provide context for UI elements and processes that users might not be familiar with
- Organize related content as subsections rather than separate sections when it improves flow
- Use link formats that work with link checkers (avoid "docs" prefixes that cause validation issues)
- Keep content focused and avoid overwhelming lists in introductory sections

Example of user-centric approach:
```markdown
<!-- Instead of leading with technical details -->
# Build Your Own Nx Plugin: Integrating Biome in 20 Minutes

<!-- Lead with user benefits -->
# Using Biome with Nx: Fast Linting and Formatting
Learn how to integrate Biome for faster linting. You don't need a plugin to get started, but creating one will make your workflow smoother.
```

This approach ensures documentation serves users effectively rather than just being technically accurate.

---

## normalize config sources

<!-- source: likec4/likec4 | topic: Configurations | language: TypeScript | updated: 2025-11-06 -->

Ensure all runtime and project configuration is explicit, type-safe, and machine-independent.

Motivation
- Implicit or ad-hoc config (raw process.env usage, feature flags only in local env, or file:///absolute asset paths) causes type errors, unresolved imports, and “works on my machine” failures in CI and collaborators’ environments.

Rules (actionable)
1. Use a typed env accessor and parse values with defaults
   - Avoid raw process.env access across codebase. Use a shared helper (e.g. std-env or a thin wrapper) so values are typed and consistent.
   - Parse numeric/env values explicitly and provide sane defaults.
   Example:
   import { env } from 'std-env'

   const preferredPort = env.PORT ? parseInt(env.PORT, 10) : 5173

2. Put feature flags and experimental toggles in project config
   - Add an explicit experimental block to your project schema so flags are part of repository config and travel with the project/CI.
   - Prefer schema validation (Zod or equivalent) so configs are discoverable and validated at startup/build time.
   Example:
   export const LikeC4ExperimentalSchema = z.object({
     dynamicViewBranches: z.boolean().optional().meta({ description: '...' })
   })

   export const LikeC4ProjectJsonConfigSchema = z.object({
     // ...
     experimental: LikeC4ExperimentalSchema.optional()
   })

3. Normalize asset and file paths in generated/virtual modules
   - Disallow file:// URIs in model/config data. Convert them to repository-relative or project-root-relative paths.
   - When emitting imports in virtual modules for Vite, compute paths relative to the source file or use Vite’s filesystem prefix (/@fs) if appropriate. Test that ?inline requests resolve in dev and build.
   - Detect local images (e.g. startsWith('.') or no protocol) and rewrite imports so Vite can resolve them: e.g. `import Icon from './path/to/icon.svg?inline'` or `/@fs/path/to/icon.svg?inline` after computing correct project-relative path.

Checks to run
- Typecheck: ensure env access types and schema types pass.
- Dev server import-analysis: run Vite and verify no "Failed to resolve import" errors for generated virtual modules.
- CI reproducibility: ensure project config (including experimental flags) is present in repository and yields same behavior in CI as locally.

Why this helps
- Makes configuration explicit and versioned with the project (avoids "works on my machine").
- Prevents subtle runtime failures from unresolved imports or incorrect env parsing.
- Improves developer experience and CI reliability by standardizing where and how configuration is read and validated.

---

## platform-specific config

<!-- source: wavetermdev/waveterm | topic: Configurations | language: TypeScript | updated: 2025-11-01 -->

Centralize OS-specific configuration and modifier mappings in a dedicated config/adapter module and document global declaration files. Motivation: key modifiers (Cmd/Meta/Alt/Option), global shortcuts, and shared types behave differently across platforms; putting the logic in one place avoids inconsistent handling, duplicate OS checks, and brittle startup code.

Rules and how to apply:
- Create a single platform config module (e.g., src/config/platform.ts) that exports: current OS flags, a modifier mapping helper, and shortcut-registration helpers. Use this module everywhere for pretty-printing, key matching, and registering global shortcuts.
- Implement default platform semantics but allow explicit overrides: treat logical modifiers (Cmd, Meta, Option) as mapped to actual keys per OS, but if a keybind explicitly specifies Meta or Alt, respect that override.
- Make global .d.ts declaration files the canonical place for shared ambient types and document them (custom.d.ts, gotypes.d.ts). Do not scatter duplicate imports for those globally declared types.
- Ensure startup registration is OS-aware and idempotent: perform OS checks before registering platform-specific shortcuts and make registration reset/re-register safe on restart.

Code examples (patterns to follow):
- Platform mapping helper (conceptual)
const isMac = process.platform === "darwin";
export function mapLogicalModifier(mod: 'Cmd' | 'Meta' | 'Option') {
    if (mod === 'Cmd') return isMac ? 'Meta' : 'Alt';
    if (mod === 'Option') return isMac ? 'Alt' : 'Alt';
    return 'Meta'; // fallback
}

- Use mapping in prettyPrintKeybind:
function prettyPrintKeybind(keyDescription: string): string {
    const keyPress = parseKeyDescription(keyDescription);
    const mappedMods = {
        Cmd: mapLogicalModifier('Cmd'),
        Option: mapLogicalModifier('Option'),
        // respect explicit Meta/Alt in keyPress.mods if present
    };
    // build display string using mappedMods and platform symbols
}

- OS-aware global shortcut registration:
if (isMac) {
    reregisterGlobalShortcut('Cmd+F4');
} else if (process.platform === 'linux' || process.platform === 'win32') {
    reregisterGlobalShortcut('Alt+F4');
}

Practical checklist for PRs:
- Add or update platform mapping only in the config/adapter module, not inline in multiple files.
- Document any global types in custom.d.ts/gotypes.d.ts and reference them in code reviews.
- If a binding explicitly includes Meta/Alt, ensure the handler honors that instead of applying the default mapping.
- Confirm global shortcut registration is guarded by OS checks and that startup re-registration is safe and intentional.

This ensures consistent cross-platform behavior, easier testing and maintenance, and a single place to update OS-specific settings.

---

## synchronize declared versions

<!-- source: nrwl/nx | topic: Configurations | language: Toml | updated: 2025-11-01 -->

Ensure that version declarations in configuration files accurately reflect the versions actually being used in runtime environments. Configuration drift occurs when declared versions diverge from deployed versions, leading to inconsistent environments and potential deployment issues.

When updating configuration files, verify that the specified versions match what's currently deployed or intended for deployment. Avoid situations where configuration declares one version while the system runs another.

Example from mise.toml:
```toml
# Bad: Config says node 24, but runtime uses 20.19
node = "24"  # Actually running 20.19

# Good: Config matches runtime
node = "20.19"  # Matches actual deployed version
```

Before committing configuration changes, validate that:
- Declared versions match intended deployment versions
- Manual installations are replaced with proper configuration management
- Version specifications are consistent across all environment configuration files

---

## Thread ownership clarity

<!-- source: nrwl/nx | topic: Concurrency | language: Rust | updated: 2025-10-24 -->

When designing concurrent systems, ensure data ownership is explicit and clear at thread boundaries. Avoid passing references across threads or using indirect access patterns that obscure ownership responsibilities.

In multithreaded code, data must be owned by the thread that uses it, not borrowed from another thread. This prevents race conditions and makes the code's concurrency model explicit.

Example of problematic pattern:
```rust
// BAD: Trying to pass &mut self to a thread
fn start_collection(&mut self) -> Result<(), Error> {
    std::thread::spawn(|| {
        self.collection_loop(); // Error: can't pass references across threads
    });
}
```

Example of correct pattern:
```rust
// GOOD: Clone Arc references for thread ownership
fn start_collection(&mut self) -> Result<(), Error> {
    let should_collect = Arc::clone(&self.should_collect);
    let system = Arc::clone(&self.system);
    
    std::thread::spawn(move || {
        Self::collection_loop(should_collect, system); // Owned data
    });
}
```

Additionally, avoid indirect data access that obscures ownership. Instead of retrieving data through unrelated objects, pass required data directly to maintain clear responsibility chains and prevent confusion about data sources in concurrent contexts.

---

## Configuration documentation clarity

<!-- source: nrwl/nx | topic: Configurations | language: Other | updated: 2025-10-23 -->

Configuration changes and examples should be documented with clear formatting, proper context, and helpful references to aid developer understanding.

When documenting configuration changes:
- Add filename comments to code blocks to provide context
- Use diff blocks to clearly show before/after states for configuration migrations
- Include links to relevant reference documentation for configuration options
- Consolidate related configuration information rather than scattering it across multiple sections

Example of clear configuration documentation:

```diff
// nx.json
{
  "plugins": [
    {
      "plugin": "@nx/dotnet",
      "options": {
-       "inferredTargets": {
-         "build": "build",
-         "test": {
-           "targetName": "test:dotnet",
-           "cache": false
-         }
-       }
+       "build": {
+         "targetName": "build"
+       },
+       "test": {
+         "targetName": "test:dotnet"
+       }
      }
    }
  ]
}
```

This approach helps developers quickly understand what configuration files are being modified, what specific changes are needed, and where to find additional information about configuration options.

---

## Documentation metadata consistency

<!-- source: nrwl/nx | topic: Documentation | language: Other | updated: 2025-10-23 -->

Ensure documentation uses consistent structural elements and proper metadata to optimize user experience and content discoverability. Use platform-native components (like `aside` instead of `callout` for Astro docs), include appropriate sidebar labels, and leverage weight/filter properties to control search result prominence.

Key practices:
- Use consistent documentation components that are native to your platform
- Add explicit sidebar labels when the page title isn't suitable for navigation
- Use weight values (like 0.1 or 0.5) to deprioritize less useful content in search results
- Apply filter metadata to categorize content appropriately

Example frontmatter:
```yaml
---
title: 'affected:graph - CLI command'
sidebar:
  label: Introduction
weight: .1
filter: "type:References"
---
```

This approach prevents deprecated or less relevant content from dominating search results while ensuring users can navigate documentation intuitively.

---

## Avoid code duplication

<!-- source: nrwl/nx | topic: Code Style | language: TypeScript | updated: 2025-10-22 -->

Before implementing new functionality, check if similar utilities or patterns already exist in the codebase. Reuse existing code rather than duplicating logic, and organize shared types and constants in centralized locations to prevent circular dependencies and maintain consistency.

Key practices:
- Search for existing utilities before creating new ones (e.g., "There is already a `isPrerelease` utility in `packages/nx/src/command-line/release/utils/shared.ts`, let's not duplicate the logic")
- Extract shared types to common files to avoid circular dependencies
- Use generic patterns instead of creating multiple similar functions
- Remove unused variables and unnecessary abstractions

Example of good practice:
```typescript
// Instead of creating multiple similar selectors
export function getMigrationType(ctx: AutomaticMigrationState, migrationId: string) {
  return ctx.nxConsoleMetadata?.completedMigrations?.[migrationId]?.type;
}

// Then use it in components with comparison
const isSuccessful = getMigrationType(ctx, id) === 'successful';
const isFailed = getMigrationType(ctx, id) === 'failed';
```

This approach reduces code duplication, improves maintainability, and ensures consistent behavior across the codebase.

---

## Use explicit, consistent names

<!-- source: nrwl/nx | topic: Naming Conventions | language: TypeScript | updated: 2025-10-22 -->

Variable and parameter names should be explicit about their purpose and consistent with established naming patterns in the codebase. Avoid ambiguous or generic names that could be confusing in context.

**Make names explicit and descriptive:**
- Use `versionActionsVersion` instead of `version` when the context involves multiple version concepts
- Use `tasksExecutionId` or `executionId` instead of generic `taskId` when referring to execution identifiers
- Use `getAtomizedTaskEnvVars` instead of `getOutputEnvVars` when the function has a specific scope

**Follow established naming conventions:**
- Maintain consistent casing patterns (e.g., `releaseTagPatternStrictPreId` not `releaseTagPatternStrictPreid`)
- Follow existing formatting conventions (e.g., use `is_golden` not `isGolden` when other properties use underscores)

Example:
```typescript
// Avoid: Generic and potentially confusing
const taskId = hashArray([...process.argv, Date.now().toString()]);
const version = getVersion();

// Prefer: Explicit and descriptive  
const tasksExecutionId = hashArray([...process.argv, Date.now().toString()]);
const versionActionsVersion = getVersionActionsVersion();
```

---

## Use nullish coalescing operators

<!-- source: nrwl/nx | topic: Null Handling | language: TypeScript | updated: 2025-10-22 -->

Prefer modern JavaScript nullish coalescing (`??`) and optional chaining (`?.`) operators over verbose conditional logic for handling null and undefined values. These operators provide cleaner, more readable code while maintaining null safety.

Use nullish coalescing to provide fallback values:
```typescript
// Instead of complex conditional logic
let newVersion: string;
if (targetVersionData.newVersion === null) {
  newVersion = this.releaseGraph.cachedCurrentVersions.get(dep.target) || currentDependencyVersion;
} else {
  newVersion = targetVersionData.newVersion || currentDependencyVersion;
}

// Use nullish coalescing
const newVersion = 
  targetVersionData.newVersion ?? 
  this.releaseGraph.cachedCurrentVersions.get(dep.target) ?? 
  currentDependencyVersion;
```

Use optional chaining for safe property access:
```typescript
// Safe property access
projectVersionData?.newVersion

// Ensure operators stay together (not split across lines)
delete rootVersionWithoutGlobalOptions.generatorOptions?.someProperty;
```

Add defensive checks even when values "shouldn't" be null, and verify types before operations when parameters can be multiple types:
```typescript
// Protect against unexpected nulls
const preId = prerelease(version)?.[0];
if (typeof preId === 'string') {
  return preId;
}

// Type check before processing
function concurrency(str: string | number) {
  const parallel = typeof str === 'number' ? str : parseInt(str);
}
```

---

## Manage bindings and state

<!-- source: wavetermdev/waveterm | topic: React | language: TSX | updated: 2025-10-21 -->

Ensure components explicitly initialize reactive state, manage input/keybinding lifecycle, and decide whether children should subscribe to live atoms or use a stable snapshot.

Why: Discussions repeatedly show bugs from missing MobX setup, duplicated or double-registered keybindings, accidental live updates that change UI unexpectedly, and inconsistent key handling logic. This guideline makes component behavior predictable and prevents leaks, duplicate handlers, and surprising re-renders.

How to apply (practical checklist):
- Initialize MobX observables in class components. In the constructor call mobx.makeObservable(this, { /* annotations */ }).
  Example:
  constructor(props) {
      super(props);
      mobx.makeObservable(this, { someState: mobx.observable, someAction: mobx.action });
  }

- Guard per-instance keybinding registration and always clean up. Use a per-instance domain name and a boolean observable to avoid double registration. Unregister the domain on unmount.
  Example pattern:
  keybindsRegistered = mobx.observable.box(false);

  componentDidMount() {
      if (!this.keybindsRegistered.get()) {
          mobx.action(() => this.keybindsRegistered.set(true))();
          const domain = `datepicker-${this.uuid}-${part}`;
          GlobalModel.keybindManager.registerKeybinding("control", domain, "generic:selectLeft", () => { /*...*/; return true; });
          // register other keys
      }
  }

  componentWillUnmount() {
      GlobalModel.keybindManager.unregisterDomain(`datepicker-${this.uuid}`);
      mobx.action(() => this.keybindsRegistered.set(false))();
  }

- Decide snapshot vs subscription intentionally:
  - If a modal or view must remain stable once opened (should not disappear mid-use), read a snapshot once (e.g., store initial value in a ref) and avoid subscribing to live updates.
    Example: initialVersionRef.current = clientData.meta?.["onboarding:lastversion"] ?? "v0.0.0";
  - If you pass atoms/observable values to children, ensure the child subscribes to the atom (or expose a stable derived value) so changes propagate correctly. If passing an atom, the child must read/subscribe to it.

- Use centralized key-check utilities for consistent cross-platform modifier handling instead of ad-hoc e.code and getModifierState checks.
  Example: if (GlobalModel.checkKeyPressed(e, GlobalModel.KeyPressModifierControl + ":g")) { /* ... */ }

- When using props with reactive frameworks (Preact/MobX quirks), if direct access triggers warnings, copy props into component fields/observables in the constructor to stabilize access.
  Example: this.props_ = props; // or makeObservable-backed copy if needed

- Prefer reuse of components/resources (keybinding modules, shared UI pieces) rather than duplicating logic across similar views. Extract shared keybinding registration or UI into a reusable component or hook.

- Always document domain naming and lifecycle expectations for keybinding consumers to avoid collisions and duplicate registrations.

Benefits: predictable lifecycle, fewer memory leaks or double-registrations, clearer intent about subscription semantics, consistent key handling, and easier reuse of UI and logic across components.

---

## API documentation accuracy

<!-- source: nrwl/nx | topic: API | language: Other | updated: 2025-10-21 -->

Ensure API documentation examples use types, interfaces, and imports that actually exist in the documented versions. Verify that code examples can be successfully imported and executed before publishing documentation.

When documenting API lifecycle information (deprecation timelines, future removals), validate these claims with maintainers rather than making assumptions. Avoid stating definitive future plans unless they are confirmed by the development team.

Example of problematic documentation:
```typescript
// Bad: Importing a type that doesn't exist in @nx/devkit@22+
import {
  CreateNodes,  // This type was removed!
  CreateNodesV2,
} from '@nx/devkit';
```

Example of corrected documentation:
```typescript
// Good: Only import types that exist in the target version
import {
  CreateNodesV2,
  CreateNodesContextV2,
} from '@nx/devkit';
```

Before documenting deprecation timelines, confirm with maintainers:
- "Nx 24: The createNodesV2 types will be removed" ← Verify this is actually planned
- Check if exports will truly be removed or just marked as deprecated

This prevents developers from following outdated or incorrect API guidance and ensures documentation remains a reliable reference.

---

## Use type-specific variable names

<!-- source: jj-vcs/jj | topic: Naming Conventions | language: Rust | updated: 2025-10-18 -->

Use distinct variable names that reflect their types to avoid confusion and make code intent clearer. Avoid reusing the same variable name for different types within the same scope or related functions.

This prevents confusion when tracking values as they pass through functions and makes the code more maintainable. When variables of different types serve similar purposes, use descriptive suffixes or prefixes that indicate the type.

Example from the codebase:
```rust
// Bad: Same name for different types
let executable: bool = file.is_executable();
let executable: FileExecutableFlag = FileExecutableFlag::from(executable);

// Good: Type-specific names
let executable: bool = file.is_executable();
let exec_bit: ExecBit = ExecBit::from(executable);
```

Other examples:
- Use `handle` instead of `val` for `same_file::Handle` objects
- Use `remote_branch` instead of ambiguous `origin` for branch parameters
- Distinguish between `remote_url` and `push_url` when both are URLs but serve different purposes

This practice is especially important in functions that transform data between types or when working with similar concepts at different abstraction levels.

---

## Use safe optional defaults

<!-- source: jj-vcs/jj | topic: Null Handling | language: Rust | updated: 2025-10-17 -->

When working with optional values, prefer safe extraction methods that provide defaults rather than methods that can panic. Use `unwrap_or()`, `unwrap_or_default()`, or `unwrap_or_else()` instead of `unwrap()` to handle `None` cases gracefully.

This pattern prevents runtime panics and makes code more robust by explicitly handling the absence of values. It's particularly important when dealing with configuration values, map lookups, or any operation that might not return a result.

Examples of good patterns:
```rust
// Instead of potentially panicking
let executable = file.executable.unwrap();

// Use safe defaults
let executable = file.executable.unwrap_or(false);

// For common defaults
let config = maybe_read_to_string(&path)?.unwrap_or_default();

// For map lookups
let parent = old_to_new.get(p.id()).unwrap_or(&p);
```

This approach makes the code's behavior predictable and prevents unexpected crashes when optional values are absent, while clearly documenting the intended fallback behavior.

---

## defensive null handling

<!-- source: wavetermdev/waveterm | topic: Null Handling | language: TypeScript | updated: 2025-10-17 -->

Always handle nullable values explicitly and defensively to prevent runtime null/undefined errors and to make intent clear.

Why: Nulls and undefined values cause intermittent runtime exceptions and unclear state transitions. Being explicit—both when clearing values and when checking inputs—reduces bugs and documents intent.

Rules to follow:
- Use optional chaining or explicit null/undefined checks before accessing properties or collection lengths (e.g., workspaceList?.length).
- Wrap parsing/decoding in try/catch and set values to null when parsing fails or data is absent to represent a cleared value.
- When multiple related conditions control behavior, combine them so the intended branch is obvious and you don’t accidentally act on a null value.

Examples (based on discussion snippets):
1) Defensive parsing and explicit null to clear state

try {
    const decodedCmd = atob(cmd.data.cmd64);
    rtInfo["shell:lastcmd"] = decodedCmd;
} catch (e) {
    console.error("Error decoding cmd64:", e);
    // null used intentionally to clear the key
    rtInfo["shell:lastcmd"] = null;
}

2) Combine guards and use optional chaining for nullable collections

if (ww?.workspaceId === workspaceId) {
    if (workspaceList?.length > 1) {
        // switch workspace
    } else {
        // delete workspace
    }
}

Apply these consistently: prefer explicit null to indicate cleared/absent values, guard all external inputs and collections with optional chaining or null checks, and structure conditionals to make null-handling intent obvious.

---

## Use Contextual Sanitization

<!-- source: mermaid-js/mermaid | topic: Security | language: TypeScript | updated: 2025-10-16 -->

Any diagram text/config that can originate from users (node labels, tooltips, markdown, theme/style tokens, and link targets) must be treated as untrusted. Apply **context-appropriate** escaping/sanitization and avoid security-by-regex.

Practical rules:
- **HTML insertion:** If you must use `.html(...)`, sanitize the string (e.g., `DOMPurify`/`rehype-sanitize`) and/or ensure all metacharacters are escaped. If you only need plain text, prefer `.text(...)`.
- **SVG/CSS URL tokens:** When constructing values for `url(...)` in SVG/CSS, use `CSS.escape()` (or equivalent) instead of manual `replace` chains.
- **Markdown to HTML:** Treat markdown-to-HTML as an HTML generation pipeline. Prefer a sanitize step and don’t assume “micromark is safe” means “output is safe to inject.”
- **Link targets:** Do not allow dangerous schemes like `javascript:` in any “click”/link rendering path. Add tests that ensure unsafe schemes are rejected/neutralized.
- **Validation for style/config:** For theme/style properties that become CSS (colors, sizes, weights, radii), validate formats/ranges before using them.

Example patterns:
- Plain text (safe default):
  ```ts
  tooltipEl.text(userProvidedTitle); // avoid .html for untrusted strings
  ```
- Contextual escaping for CSS URL tokens:
  ```ts
  const safeToken = CSS.escape(untrustedToken);
  const css = `url(${safeToken})`;
  ```
- Validate config inputs before using as CSS:
  ```ts
  function isValidHexColor(s: string) {
    return /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.test(s);
  }
  if (theme.primaryColor && !isValidHexColor(theme.primaryColor)) throw new Error('Invalid color');
  ```

---

## Ensure configuration consistency

<!-- source: nrwl/nx | topic: Configurations | language: Json | updated: 2025-10-16 -->

Configuration files should maintain consistency in patterns, use correct paths and values, and follow established conventions across the codebase. This includes proper output paths, consistent dependency versioning patterns, and appropriate dependency categorization.

Key areas to verify:
- **Output paths**: Use correct directory structures (e.g., `dist/lib` instead of `{projectRoot}/src/lib`)
- **Dependency versioning**: Maintain consistent patterns within the same configuration scope (e.g., if using caret `^` for similar packages, apply it consistently)
- **Dependency categorization**: Place dependencies in appropriate sections (`dependencies` vs `devDependencies`)
- **Version alignment**: Check for potential conflicts with other changes and align with ecosystem standards when possible

Example from package.json:
```json
{
  "dependencies": {
    "@module-federation/enhanced": "^0.17.0",  // Keep caret for consistency
    "@module-federation/sdk": "^0.17.0"
  },
  "devDependencies": {
    "@nx/cypress": "workspace:*"  // Move dev-only deps here
  }
}
```

---

## consistent command flag design

<!-- source: jj-vcs/jj | topic: API | language: Rust | updated: 2025-10-15 -->

Design command-line interfaces with consistent flag semantics and leverage framework features for validation. Avoid ambiguous syntax that can be interpreted multiple ways, use explicit conflict declarations instead of manual validation, and ensure flag combinations have clear, predictable behavior.

Key principles:
- Use clap's built-in `conflicts_with` instead of manual validation: `#[arg(long, conflicts_with = "other_flag")]`
- Separate command and arguments for better help messages: prefer `command: String, args: Vec<String>` over `command: Vec<String>`
- Avoid ambiguous syntax like accepting both "rs" and ".rs" for the same meaning
- Define clear semantics for flag combinations (intersection vs union behavior)
- Use exhaustive pattern matching for validation to prevent logic drift

Example of good flag design:
```rust
#[derive(clap::Args)]
struct Args {
    #[arg(long, conflicts_with = "push")]
    fetch: bool,
    
    #[arg(long, conflicts_with = "fetch")]  
    push: bool,
    
    // Clear semantics: when neither specified, both are true
    // When one specified, only that one is true
}
```

This ensures users can predict behavior and reduces maintenance burden by leveraging framework validation.

---

## Choose efficient data structures

<!-- source: jj-vcs/jj | topic: Algorithms | language: Rust | updated: 2025-10-15 -->

Select data structures and algorithms based on their performance characteristics and expected usage patterns. Consider the size of collections, access patterns, and computational complexity when making implementation choices.

**Key considerations:**
- Use `HashSet` instead of `Vec` for membership testing when collections can be large
- Choose data structures that preserve order when sequence matters (e.g., `IndexMap` vs `HashMap`)
- Prefer more efficient algorithms when available (e.g., checking if a commit is a head vs. evaluating all children)
- Combine operations to reduce computational overhead (e.g., union revset expressions rather than evaluating separately)

**Example:**
```rust
// Instead of Vec for large collections with frequent lookups
let already_tracked_bookmarks: Vec<String> = ...;
if already_tracked_bookmarks.contains(&bookmark) { ... } // O(n) lookup

// Use HashSet for O(1) average lookup time
let already_tracked_bookmarks: HashSet<String> = ...;
if already_tracked_bookmarks.contains(&bookmark) { ... } // O(1) lookup
```

This applies especially when dealing with user-facing operations that may scale with repository size or when processing large collections where the choice of data structure significantly impacts performance.

---

## prioritize documentation clarity

<!-- source: jj-vcs/jj | topic: Documentation | language: Rust | updated: 2025-10-14 -->

Write documentation that prioritizes user understanding over technical precision. Avoid unclear phrases, overly technical explanations, and unhelpful references. When in doubt, choose clarity over brevity, especially for user-facing documentation that may be someone's first encounter with a feature.

Key principles:
- Replace unclear phrases with specific, concrete language (e.g., "does not undo the effects on the remote" instead of "does not undo the push itself")
- Add user-friendly explanations for commands and features, explaining their use-case and context
- Simplify overly technical descriptions that sound like code explanations rather than user guidance
- Make references to familiar concepts rather than asking users to "read the source code" or "experiment"
- When documentation might be someone's first reference point, err on the side of being more comprehensive and clear, even if longer

Example of improvement:
```rust
// Before: Technical and unclear
/// Template which, upon being forced (`extract()`ed), will evaluate its
/// condition and select between a template for the true case and a template
/// for the false case (which will yield nothing if it is [`None`]).

// After: Clear and user-focused  
/// Template which selects output based on a boolean condition.
```

This approach ensures documentation serves its primary purpose: helping users understand and effectively use the code.

---

## Context-aware configuration logic

<!-- source: nrwl/nx | topic: Configurations | language: Rust | updated: 2025-10-14 -->

Configuration logic should adapt based on environmental context rather than using static values. Examine the current environment state (file system, process hierarchy, feature flags) and adjust configuration accordingly to ensure optimal behavior in different scenarios.

When implementing configuration logic, consider:
- Check environmental conditions before applying configuration
- Use conditional logic to adapt behavior based on context
- Combine multiple configuration sources intelligently

Example from file walker configuration:
```rust
walker.git_ignore(use_ignores);
if use_ignores {
    // disable the parent gitignore if the directory is a git repo, otherwise use the parent gitignore
    walker.parents(!directory.join(".git").exists());
    walker.add_custom_ignore_filename(".nxignore");
}
```

This approach ensures that configuration decisions are made based on actual environmental state rather than assuming a one-size-fits-all approach. For instance, when `NX_ISOLATE_PLUGINS=true NX_DAEMON=false`, the system adapts its process architecture accordingly, with the main process managing plugin workers as child processes.

---

## scope CI access tokens

<!-- source: nrwl/nx | topic: CI/CD | language: Markdown | updated: 2025-10-13 -->

{% raw %}
Configure CI pipelines to use appropriately scoped access tokens based on branch protection status. Use read-write tokens only for protected branches (branches that don't allow direct push) and read-only tokens for all other branches and environments.

Read-write tokens allow full cache access but should be restricted to trusted environments to prevent cache poisoning. Read-only tokens allow reading from the shared primary cache and writing to branch-specific isolated caches, providing cache benefits while maintaining security.

Additionally, ensure CI commands are non-interactive by using appropriate flags like `--yes` to prevent pipelines from hanging on user prompts.

```yaml
# GitHub Actions example
jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - run: npx nx affected -t build,lint,test
      - run: npx nx release --yes  # Prevent prompts in CI
    env:
      # Use read-write token for protected branches only
      NX_CLOUD_ACCESS_TOKEN: ${{ github.ref == 'refs/heads/main' && secrets.NX_CLOUD_ACCESS_TOKEN_RW || secrets.NX_CLOUD_ACCESS_TOKEN_RO }}
```

This approach prevents unauthorized cache modifications while maintaining the performance benefits of remote caching across all CI runs.
{% endraw %}

---

## Consistent naming conventions

<!-- source: jj-vcs/jj | topic: Naming Conventions | language: Markdown | updated: 2025-10-12 -->

Maintain consistent naming and terminology throughout code and documentation. This includes proper capitalization of product names, technical terms, and consistent use of domain-specific vocabulary.

Key guidelines:
- Capitalize proper nouns consistently: "Jujutsu" not "jujutsu", "Git" not "git"
- Use consistent capitalization for technical terms: "change ID" not "change id"  
- Apply consistent heading formats: use sentence case for headings
- Prefer domain-specific terminology over generic terms: "revisions" instead of "commits" when working with Jujutsu concepts
- Choose names that fit existing patterns in the codebase: if you have `jj revert`, use `jj op revert` for consistency
- Avoid overloaded terms that have different meanings in other systems

Example corrections:
```markdown
# Before
### Commit Evolution (Change-IDs and Changes)
amend or rewrite your commits
change id

# After  
### Commit evolution (change IDs and changes)
update your revisions
change ID
```

This ensures users can easily understand and predict naming patterns, reducing cognitive load and improving overall code/documentation quality.

---

## Define technical terms clearly

<!-- source: jj-vcs/jj | topic: Documentation | language: Markdown | updated: 2025-10-11 -->

Always define technical terms and concepts explicitly in documentation rather than assuming reader knowledge. Avoid ambiguous phrasing that could be interpreted multiple ways.

When introducing technical terms:
- Provide clear, concise definitions inline rather than relying solely on external links
- Use precise language that eliminates ambiguity
- Be explicit about technical concepts even if they seem obvious

Examples of good practice:
```markdown
# Good: Clear definition
* `.trailers() -> List<Trailer>`: The trailers at the end of the commit 
  description that are formatted as `<key>: <value>`.

# Bad: Ambiguous phrasing  
* `.trailers() -> List<Trailer>`: The trailers at the end of the commit
  description, formatted as `<key>: <value>`.
```

```markdown
# Good: Precise terminology
* `.synced() -> Boolean`: For a local bookmark, true if synced with all tracked remotes.

# Bad: Imprecise terminology
* `.synced() -> Boolean`: For a local bookmark, true if synced with all remotes.
```

This prevents confusion, reduces the need for readers to maintain external references, and ensures documentation is self-sufficient. Pay special attention to terms that may have different meanings in different contexts or tools.

---

## optimize remote fetch operations

<!-- source: jj-vcs/jj | topic: Networking | language: Rust | updated: 2025-10-11 -->

When implementing network operations that fetch data from remote sources, configure specific refspecs or patterns to fetch only the required data rather than everything available. This reduces network bandwidth usage, improves performance, and ensures future operations remain efficient.

For Git remote operations, specify target branches/bookmarks explicitly:

```rust
// Instead of fetching everything
expand_fetch_refspecs(remote_name, vec![StringPattern::everything()])

// Fetch only specified branches
expand_fetch_refspecs(
    remote_name,
    target_branches
        .unwrap_or(&[StringPattern::everything()])
        .to_vec(),
)
```

Configure remotes with specific refspecs so that future fetch operations automatically use the same selective patterns. This prevents unnecessary network traffic and keeps the local repository focused on relevant data.

The same principle applies to other network operations: be explicit about what data you need rather than fetching everything available, and persist these preferences for consistency across operations.

---

## eliminate redundant code

<!-- source: jj-vcs/jj | topic: Code Style | language: Rust | updated: 2025-10-10 -->

Remove unnecessary code, operations, and annotations that don't add value. This includes redundant type annotations when types are already constrained, unnecessary conditional checks, redundant operations like path normalization in multiple places, and overly complex patterns that can be simplified.

Examples of improvements:
- Remove redundant type annotations: `let out_property: BoxedTemplateProperty<'a, bool> =` → `let out_property =` when the type is already constrained by the function signature
- Simplify conditional logic: `if created_dirs.write().await.insert(dir_path.clone()) {` → just use `created_dirs.write().await.insert(dir_path.clone());` when the condition isn't needed
- Use direct returns: `match expression.evaluate(repo) { Ok(_) => Ok(()), Err(e) => Err(e) }` → `expression.evaluate(repo).map(|_| ())`
- Avoid unnecessary variable assignments: Instead of `let mut hint = ui.hint_default(); writeln!(hint, "...")?;`, directly use `writeln!(ui.hint_default(), "...")?;`
- Remove redundant operations: Don't perform the same normalization (like path canonicalization) in multiple places when it can be done once by the caller

Focus on the principle that code should be as simple and direct as possible while maintaining clarity and correctness.

---

## Config file naming clarity

<!-- source: jj-vcs/jj | topic: Configurations | language: Rust | updated: 2025-10-10 -->

Use descriptive, unambiguous names for configuration files to clearly indicate their scope and prevent user confusion about configuration hierarchy.

When introducing new configuration files, especially in systems with multiple configuration layers (user, repo, workspace), choose names that explicitly indicate the scope rather than generic names that could be mistaken for broader configuration files.

For example, prefer `.jj/workspace-config.toml` over `.jj/config.toml` when the configuration is workspace-specific, as users might assume `.jj/config.toml` is the primary repository configuration file and overlook `.jj/repo/config.toml`.

```rust
// Good: Clear scope indication
let workspace_config_path = workspace_root.join(".jj").join("workspace-config.toml");
let repo_config_path = repo_root.join(".jj").join("repo").join("config.toml");

// Avoid: Ambiguous naming that could confuse users
let config_path = workspace_root.join(".jj").join("config.toml"); // Could be mistaken for main config
```

Consider the user's mental model when navigating configuration files. If multiple configuration files exist in the same conceptual space, their names should make the hierarchy and precedence clear at first glance. This reduces support burden and prevents configuration mistakes.

---

## robust algorithm implementation

<!-- source: nrwl/nx | topic: Algorithms | language: TypeScript | updated: 2025-10-08 -->

Implement algorithms that handle edge cases and avoid brittle assumptions about input data or structure formats. Instead of relying on simple string manipulation or assuming data structure behavior, use comprehensive approaches that account for various scenarios.

For parsing operations, handle multiple input formats:
```javascript
// Brittle approach
const target = task.target.target.split('--')[0];
const lines = content.split('\n');

// Robust approach  
const target = getTargetFromMetadata(task, projectGraph);
const lines = content.split(/\r\n|\r|\n/);
```

For data structure access, verify assumptions and implement proper traversal:
```javascript
// Assumption-based approach
const children = reflection.children;

// Verified approach
const childReflections = reflections.filter(
  (r) => r.parent && r.parent.id === reflection.id
);
```

This approach prevents bugs caused by incomplete parsing, platform differences, or incorrect assumptions about data structure behavior, leading to more reliable and maintainable code.

---

## externalize configuration values

<!-- source: nrwl/nx | topic: Configurations | language: JavaScript | updated: 2025-10-07 -->

Configuration values should be externalized from code and read from standard locations like package.json or environment variables. Implement environment-aware validation that fails fast in production when required configuration is missing, while providing sensible defaults for development environments.

For environment variables, validate required values at application startup:

```javascript
if (!process.env.NEXT_PUBLIC_ASTRO_URL) {
  // If we're building for production throw error as each env must set this value.
  if (process.env.NODE_ENV === 'production') {
    throw new Error(
      `The NEXT_PUBLIC_ASTRO_URL environment variable is not set. Please set it to the URL of the Astro site.`
    );
  }
  // For dev, default to the canary docs.
  else {
    process.env.NEXT_PUBLIC_ASTRO_URL = 'https://master--nx-docs.netlify.app';
  }
}
```

For scripts, read configuration from package.json or config files rather than hardcoding values. This ensures configuration is centralized, version-controlled, and easily maintainable across different environments and deployment scenarios.

---

## organize testing documentation clearly

<!-- source: nrwl/nx | topic: Testing | language: Other | updated: 2025-10-06 -->

Ensure testing documentation is properly categorized and uses precise terminology to maintain clarity and accessibility. Testing concepts should be organized into appropriate sections (e.g., "Testing Tools" rather than generic categories) and described with accurate language that clearly conveys the intended meaning.

When documenting testing processes, choose precise terms that accurately describe the verification steps. For example, use "valid" instead of "correct" when referring to proposed fixes that meet acceptance criteria, as this better conveys the nature of the validation being performed.

Proper organization helps developers quickly locate relevant testing guidance, while precise terminology prevents misunderstandings about testing procedures and requirements. This approach ensures that testing documentation serves as an effective reference for development teams implementing various testing strategies.

---

## Verify test assertions

<!-- source: jj-vcs/jj | topic: Testing | language: Rust | updated: 2025-10-03 -->

Always use appropriate assertion methods in tests to ensure proper verification of command behavior. When you don't need to examine command output, use `.success()` to verify the command completed without errors. When the output content is meaningful for testing the functionality, capture and snapshot it for verification.

**Problematic approach:**
```rust
// Ignoring output when we should verify success
let _output = test_env.run_jj_in(&workspace_root, ["git", "colocation", "enable"]);

// Using .success() when output should be verified
work_dir.run_jj(["metaedit", "--author-timestamp", "2001-02-03 04:05:14.000+07:00"]).success();
```

**Better approach:**
```rust
// Use .success() when only caring about command completion
test_env.run_jj_in(&workspace_root, ["git", "colocation", "enable"]).success();

// Snapshot output when it's meaningful for verification
let output = work_dir.run_jj(["metaedit", "--author-timestamp", "2001-02-03 04:05:14.000+07:00"]);
insta::assert_snapshot!(output, @"...");
```

This practice ensures that tests properly verify both command success and expected behavior, making test failures more informative and catching regressions in command output or error handling.

---

## Document CI configuration clearly

<!-- source: nrwl/nx | topic: CI/CD | language: Other | updated: 2025-10-02 -->

Always include file path comments in CI configuration code blocks and use officially recommended setup actions for CI tools. This improves documentation clarity and ensures reliable CI pipeline configuration.

When showing configuration examples, add file path comments to help developers understand where the code belongs:

```yaml
# .github/workflows/ci.yml
name: CI
jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - run: npx nx affected -t lint test build
```

```javascript
// module-federation.config.ts
export default {
    remotes: [
        ['shop', 'https://shop.example.com'],
        ['cart', 'https://cart.example.com'],
    ]
}
```

Additionally, prefer official tool setup actions over custom alternatives. For example, continue using `pnpm/action-setup@v4` for pnpm projects since that's what the official documentation recommends, rather than implementing custom setup steps.

This approach reduces confusion about file locations, makes configurations easier to implement correctly, and ensures compatibility with tool updates and best practices.

---

## precise algorithmic terminology

<!-- source: jj-vcs/jj | topic: Algorithms | language: Markdown | updated: 2025-10-01 -->

When documenting or describing algorithmic operations, use precise, unambiguous terminology that clearly distinguishes between different types of operations. Avoid reusing terms that already have specific meanings in the domain, as this can lead to confusion about the actual algorithmic behavior.

For example, when describing set operations and graph traversals:
- Don't describe `x..y` as a "set-difference operator" when there's already a dedicated `~` operator for set difference
- Instead, describe it functionally: "`x..y` is the set of revisions introduced from x to y" (equivalent to `::y ~ ::x`)
- For graph operations like `x::y`, be specific about the traversal: "all commits along all direct paths from x to y"

This precision is especially important when operations involve complex algorithmic concepts like graph traversals, set operations, or range queries, where subtle differences in behavior can significantly impact correctness and performance. Clear terminology helps developers understand the computational complexity and expected behavior of the operations they're using.

---

## document test configurations

<!-- source: jj-vcs/jj | topic: Testing | language: Toml | updated: 2025-09-24 -->

{% raw %}
When modifying test configurations or tooling settings, provide clear explanations of what the changes actually do and why specific options were chosen. Test configuration changes can be confusing without proper context.

For commit messages, explain the current behavior and what's being changed:
```
# Good
nextest: mark tests that last >10s as "SLOW"

Nextest currently marks tests as SLOW if they take more than 5 seconds.
This increases the threshold to 10 seconds to reduce noise.

# Avoid
nextest: mark tests that last >10s as "SLOW"
```

For configuration files, consider adding comments explaining non-obvious settings:
```toml
[tasks."check:test"]
tools."cargo:cargo-nextest" = "{{vars.cargo_nextest_version}}"
# Show slow and retried tests to balance informativeness with readability
env.NEXTEST_STATUS_LEVEL="slow"
```

This prevents confusion about what configuration changes actually accomplish and helps future maintainers understand the reasoning behind specific test tool settings.
{% endraw %}

---

## Use intuitive descriptive names

<!-- source: jj-vcs/jj | topic: Naming Conventions | language: Other | updated: 2025-09-23 -->

Choose names that clearly communicate purpose and intent without requiring additional documentation or context. Names should be self-explanatory to users who encounter them for the first time.

For commands and functions, prefer descriptive verbs that indicate the action being performed. Instead of cryptic or technical references, use names that directly describe what the operation does:

```
// Poor: Unclear what "touch" does
jj touch

// Better: Clear action and target
jj metaedit
jj modify
```

For files and assets, include context about their purpose and location:

```
// Poor: Generic placement
docs/favicon.png

// Better: Organized with clear purpose
docs/images/favicon.png
docs/images/jj-logo.jpg
```

For types and data structures, avoid introducing similar names that could cause confusion. If creating new types that serve similar purposes to existing ones, either reuse the existing type or clearly deprecate the old one to maintain consistency.

This approach reduces cognitive load for developers and users, making the codebase more maintainable and intuitive to navigate.

---

## Follow established naming patterns

<!-- source: nrwl/nx | topic: Naming Conventions | language: Other | updated: 2025-09-23 -->

Ensure all identifiers, file references, and generated names follow established conventions and patterns rather than using arbitrary or hardcoded values. This includes using correct file extensions in imports, following consistent naming patterns for generated targets, and using template variables instead of hardcoded names in templates.

Key practices:
- Follow established patterns for generated names (e.g., `ciTargetName--merge-reports` with double dashes)
- Use technically correct file extensions in import statements (`.mts` vs `.mjs`)
- Use template variables instead of hardcoded identifiers in code generation

Example violations and fixes:
```typescript
// ❌ Wrong: Single dash instead of established double-dash pattern
e2e-ci-merge-reports

// ✅ Correct: Follow the established pattern with double dashes  
e2e-ci--merge-reports

// ❌ Wrong: Hardcoded name in template
import { rule, RULE_NAME } from './my-custom-rule';

// ✅ Correct: Use template variable
import { rule, RULE_NAME } from './<%= name %>';
```

This ensures consistency across the codebase and prevents confusion when names don't follow expected patterns.

---

## ensure cross-platform compatibility

<!-- source: jj-vcs/jj | topic: Configurations | language: Toml | updated: 2025-09-14 -->

{% raw %}
When creating configuration files and build tasks, prioritize cross-platform compatibility by avoiding shell-specific syntax and considering how tools discover their configuration files across different environments.

Key considerations:
- Avoid shell-specific commands that may not work on Windows (e.g., complex piping with xargs)
- Consider how tools locate configuration files - some tools search parent directories automatically while others require explicit paths
- Test configuration discovery from different working directories, not just the project root
- Document platform limitations when unavoidable

Example from mise configuration:
```toml
[tasks."check:codespell"]
description = "Check code for common misspellings"
tools.uv = "{{vars.uv_version}}"
# Good: Uses tool that auto-discovers config, works cross-platform
run = "uv run codespell"

# Avoid: Shell-specific syntax that breaks on Windows
# run = "jj file list | xargs mise run codespell"
```

This approach ensures your development environment works consistently for all team members regardless of their operating system, reducing setup friction and debugging time spent on platform-specific issues.
{% endraw %}

---

## Minimize API scope

<!-- source: jj-vcs/jj | topic: API | language: Markdown | updated: 2025-09-11 -->

When designing APIs, prioritize simplicity and focused scope over feature completeness. Before adding new API methods or expanding existing ones, evaluate whether the functionality can be achieved with existing interfaces. APIs that spread across multiple modules or introduce complex signatures often indicate scope creep that should be avoided.

Key principles:
- Question necessity: Ask "can this be achieved with existing APIs?" before adding new ones
- Limit cross-module impact: Prefer keeping functionality contained within single modules when possible  
- Simplify signatures: Avoid overly complex method signatures that take multiple generic parameters or require deep domain knowledge

For example, instead of adding a new `ext:` fileset operator when `glob:"**/*.rs"` already works, consider whether the convenience justifies the additional API surface. Similarly, when an API signature becomes complex like:

```rust
pub fn search(
    &self,
    path: &RepoPath,
    attribute_names: impl AsRef<[&str]>,
    priority: SearchPriority,
) -> Result<HashMap<String, gix_attributes::State>>
```

Consider simpler alternatives that drop unnecessary parameters or use more focused types:

```rust
pub fn search(
   &self,
   path: &RepoPath, 
   attribute_names: &[&str]
) -> Result<...>
```

This approach prevents APIs from becoming unwieldy and reduces maintenance burden while keeping the codebase more approachable for contributors.

---

## preserve error context

<!-- source: jj-vcs/jj | topic: Error Handling | language: Rust | updated: 2025-09-11 -->

When handling errors, preserve the original error context and avoid exposing internal representations to users. Use `IoResultExt::context()` to attach meaningful path information to I/O errors, and maintain error source chains using `.with_source()` or similar mechanisms.

For user-facing error messages, avoid displaying internal data structures that users cannot understand. Instead, provide clear, actionable error descriptions.

Example of good error context preservation:
```rust
// Good: Attach path context to I/O errors
std::fs::write(&jj_gitignore_path, "/*\n")
    .context(&jj_gitignore_path)?;

// Good: Preserve error source chain  
TemplateParseError::expression(message, span).with_source(err)

// Bad: Expose internal representation to user
format!("The given revset '{:?}' was expected to have {} elements", set, count)

// Good: User-friendly message
format!("revset that was expected to have {} revision had {} revisions", expected, actual)
```

This approach ensures that developers get sufficient debugging information while users receive comprehensible error messages. The error context helps with troubleshooting without overwhelming end users with implementation details.

---

## accessibility attributes for decorative elements

<!-- source: nrwl/nx | topic: Code Style | language: Other | updated: 2025-09-11 -->

Decorative images, icons, and other visual elements that don't convey meaningful content should include `aria-hidden="true"` to prevent screen readers from announcing them. This ensures a cleaner experience for users with assistive technologies and maintains consistent accessibility markup patterns across the codebase.

Apply this attribute to any img, svg, or icon elements that serve purely decorative purposes:

```html
<!-- Decorative sidebar icon -->
<img 
  src={icon} 
  alt="" 
  aria-hidden="true" 
  class="sidebar-icon w-4 h-4 dark:invert"
/>

<!-- Decorative group icon -->
<img 
  src={icon} 
  alt="" 
  aria-hidden="true" 
  class="sidebar-icon w-4 h-4 dark:invert"
/>
```

This practice should be consistently applied to maintain clean, accessible markup throughout the application.

---

## minimize resource usage

<!-- source: nrwl/nx | topic: Performance Optimization | language: TypeScript | updated: 2025-09-08 -->

Optimize performance by being selective about resource consumption - process only necessary data, avoid redundant operations, and use lightweight alternatives when possible.

Key strategies:
- **Store hashes instead of full data**: Rather than caching entire objects, store their hashes to reduce disk space and computation overhead
- **Reduce data before processing**: Filter or transform data to minimal required form before expensive operations like hashing
- **Avoid redundant operations**: Ensure expensive operations like hashing are performed only once and reused
- **Use conditional loading**: Only require/import modules when actually needed, and prefer `require.resolve()` over `require()` when you don't need to execute the module

Example:
```javascript
// Instead of storing full external nodes data
const externalNodesData = getExternalNodesData(externalNodes);
writeToCache(externalNodesData); // Large disk usage

// Store hash instead
const externalNodesHash = hashObject(getExternalNodesData(externalNodes));
writeToCache(externalNodesHash); // Minimal disk usage

// Conditional require
function assertBuilderPackageIsInstalled(packageName: string): void {
  try {
    require.resolve(packageName); // Lighter than require(packageName)
  } catch {
    throw new Error(`Package ${packageName} not found`);
  }
}
```

This approach can yield significant performance improvements - benchmarks show up to 6x speed improvements when reducing data before processing.

---

## Cache expensive calculations

<!-- source: nrwl/nx | topic: Performance Optimization | language: Rust | updated: 2025-09-08 -->

Avoid recalculating expensive operations in frequently called methods by caching results and only recalculating when necessary. This is especially important in rendering loops, event handlers, and other high-frequency code paths where the same computation may be performed repeatedly with the same inputs.

Store calculated values in instance variables or state, and invalidate the cache only when the underlying data changes. This prevents performance bottlenecks from redundant computations.

Example of the problem:
```rust
fn draw(&mut self, f: &mut Frame<'_>, area: Rect) -> Result<()> {
    // Recalculates on every draw call - expensive!
    let column_visibility = self.calculate_column_visibility(area.width);
    // ... rest of drawing logic
}
```

Example of the solution:
```rust
fn draw(&mut self, f: &mut Frame<'_>, area: Rect) -> Result<()> {
    // Only recalculate if width changed or cache is invalid
    if self.column_visibility.is_none() || self.last_width != area.width {
        self.column_visibility = Some(self.calculate_column_visibility(area.width));
        self.last_width = area.width;
    }
    let column_visibility = self.column_visibility.as_ref().unwrap();
    // ... rest of drawing logic
}
```

Consider caching at initialization or on state changes rather than in performance-critical loops. When facing circular dependencies in calculations, pre-reserve space or use conservative estimates to avoid expensive recalculation cycles.

---

## Multiple remote configuration

<!-- source: jj-vcs/jj | topic: Networking | language: Markdown | updated: 2025-09-08 -->

When documenting or implementing features that involve multiple remote repositories, provide clear guidance on different remote configuration strategies and their appropriate use cases. This includes explaining the distinction between remotes you have write access to (typically `origin`) versus read-only upstream remotes, and when to track or sync different remote branches.

For example, when documenting repository setup options, include all available initialization methods:

```shell
# Option 1: Start JJ in an existing Git repo with remotes
$ jj git init --colocate

# Option 2: Clone directly from remote
$ jj git clone <remote-url>

# Option 3: Initialize new repo and add remotes
$ jj git init
$ jj git remote add origin <your-fork>
$ jj git remote add upstream <canonical-repo>
```

Address common workflow questions explicitly, such as whether to keep fork repositories synchronized with upstream, and explain the trade-offs of different tracking strategies. This helps developers understand the networking implications of their remote configuration choices and select the approach that best fits their collaboration model.

---

## specify configuration scope

<!-- source: jj-vcs/jj | topic: Configurations | language: Markdown | updated: 2025-09-07 -->

Always explicitly specify the configuration scope using `--user` or `--repo` flags when setting configuration values with `jj config set`. This prevents ambiguity about where the configuration should be stored and ensures settings are applied at the intended level.

Use `--user` for settings that should apply across all repositories for the current user, and `--repo` for settings specific to the current repository.

Example:
```shell
# Repository-specific configuration
jj config set --repo 'revset-aliases."trunk()"' main@upstream
jj config set --repo gerrit.default_for main

# User-wide configuration  
jj config set --user gerrit.default_for main
jj config set --user git.push origin
```

Without explicit scope specification, it's unclear whether the configuration will be stored in the user's global config or the repository's local config, leading to unexpected behavior and configuration management issues.

---

## documentation formatting consistency

<!-- source: jj-vcs/jj | topic: Code Style | language: Markdown | updated: 2025-09-03 -->

Maintain consistent formatting and style patterns across all documentation to improve readability and user experience. This includes using proper shell command notation, consistent punctuation choices, and aligned configuration examples.

For shell commands, use the `$` prefix with explanatory comments:
```
$ jj upload   # "upload" is an alias using "jj util exec"
```

Choose consistent punctuation throughout documentation (prefer commas over em dashes for better readability):
```
time, exactly how Gerrit wants you to work
```

Maintain consistent configuration patterns across different tools and sections:
```toml
[language-server.rust-analyzer.config.rust-analyzer.rustfmt]
extraArgs = ["+nightly"]
```

This approach ensures that documentation maintains a professional, cohesive appearance and reduces cognitive load for readers by establishing predictable formatting patterns.

---

## Network data encoding

<!-- source: cypress-io/cypress | topic: Networking | language: TypeScript | updated: 2025-09-03 -->

Ensure network-related data like URLs and IP addresses are properly encoded and typed to prevent validation failures and type mismatches. When working with network protocols, use precise types that match the actual return values and apply consistent encoding across all network operations.

For IP family handling, use accurate type annotations:
```typescript
// Incorrect - net.isIP returns 0 for invalid IPs
const isIP = net.isIP(host) as net.family

// Correct - includes 0 for invalid IP case  
const isIP = net.isIP(host) as net.family | 0
```

For URL operations, ensure consistent encoding:
```typescript
// Incorrect - raw path may contain unencoded characters
shouldLoad: () => document.location.pathname.includes("${file.absolute}")

// Correct - properly encode URL for comparison
shouldLoad: () => document.location.pathname.includes("${encodeURI(file.absolute)}")
```

This prevents runtime errors from type mismatches and ensures URL validation works correctly when paths contain special characters.

---

## Provide actionable error messages

<!-- source: nrwl/nx | topic: Error Handling | language: TypeScript | updated: 2025-09-03 -->

When handling errors, transform technical exceptions into user-friendly messages that include clear remediation steps and actionable guidance. Avoid exposing raw technical errors to users, and instead provide context about what went wrong and how to resolve the issue.

Rather than letting technical errors bubble up:
```ts
try {
  isNpmInstalled = getPackageManagerVersion('npm', process.cwd(), true) !== '';
} catch (e) {
  throw e; // Raw technical error
}
```

Provide controlled, user-facing error messages:
```ts
try {
  isNpmInstalled = getPackageManagerVersion('npm', process.cwd(), true) !== '';
} catch (e) {
  console.error(`npm was not found in the current environment. This is only supported when using \`bun\` as a package manager, but your detected package manager is "${pm}"`);
  return { success: false };
}
```

Error messages should:
- Explain what went wrong in user terms
- Provide specific remediation steps when possible
- Include relevant context (like detected package manager)
- Mention alternative solutions or workarounds when appropriate
- Guide users to additional resources for verification (e.g., "check the package at npmjs.org")

---

## Consistent Docs Formatting

<!-- source: mermaid-js/mermaid | topic: Code Style | language: Markdown | updated: 2025-09-02 -->

For documentation, apply strict formatting rules to both code samples and embedded assets:

- Use the correct fenced-code language for rendered examples: fence Mermaid diagram samples with `mermaid-example` and keep indentation consistent.
- For diagram YAML frontmatter, follow the exact delimiter and YAML rules:
  - Use `---` on its own line (the first line must contain only `---`).
  - Keep YAML indentation consistent.
  - Treat keys/settings as case-sensitive; invalid YAML/parameters may break rendering.
  - Follow YAML syntax requirements for strings (quotes may be needed depending on content).

Example:
```markdown
---
config:
  layout: tidy-tree
---

```mermaid-example
mindmap
  root((mindmap is a long thing))
    A
    B
    C
```
```

- Image accessibility: keep `alt` text short and descriptive (avoid long sentences for banners/thumbnails).

---

## require explicit security consent

<!-- source: jj-vcs/jj | topic: Security | language: Rust | updated: 2025-09-02 -->

Always require explicit user consent and validation before executing potentially dangerous operations, especially those involving external configuration or dynamic user inputs. This prevents security vulnerabilities from being introduced through seemingly innocent features.

For external configuration (like repo-provided settings), implement a trust model that forces users to explicitly review and approve dangerous settings rather than silently executing them. As noted in the discussions: "If we do let repos set dangerous settings then we should certainly have a trust model for it."

For user inputs in templates or dynamic systems, avoid allowing arbitrary string interpolation that could lead to injection vulnerabilities. Consider restricting to literal strings or implementing strict validation, since "dealing with dynamic template strings is a known problem spot in basically every language (c.f. printf vulnerabilities in C, etc)."

Example approach for configuration:
```rust
// Bad: Silently execute repo config
load_and_execute_repo_config();

// Good: Require explicit user consent
if user_explicitly_trusts_repo_config() {
    load_and_execute_repo_config();
} else {
    show_diff_and_prompt_for_approval();
}
```

The key principle is that downloading files should never be implicit consent to execute arbitrary code, and systems should be secure by default rather than relying on users to exercise unrealistic caution.

---

## Intentional Version Pinning

<!-- source: mermaid-js/mermaid | topic: Configurations | language: Json | updated: 2025-08-28 -->

When managing configuration via `package.json`/`tsconfig.json`, treat version and target specifiers as compatibility controls—not defaults. Choose constraints based on the dependency/toolchain’s real compatibility behavior, and wire compatibility between packages explicitly.

Apply these rules:
- **Non-semver or signature-risk dependencies:** avoid `^`; use `~x.y.z` or a **fixed** version (and document the exception).
- **Compatibility-coupled packages:** if you bump one package (e.g., a runtime), verify whether related packages (e.g., `@types/*`) are fixed/unchangeable and don’t assume compatible upgrades.
- **Version range choice:**
  - Use `^` only when the dependency truly follows semver and you’re OK with patch/minor updates.
  - Use `~` when you only want patch updates.
  - Use a fixed version when you need deterministic behavior.
- **Package boundary & opt-in behavior:** if functionality is meant to be added during initialization, don’t hard-bundle those packages as workspace deps; prefer documented opt-in wiring.
- **Cross-package compatibility:** add **peerDependencies** when the library/external package version pairing matters so mismatches produce clear warnings.
- **Config file targets:** ensure `tsconfig` module/target settings match current TypeScript semantics (e.g., prefer `Node16/Node18` settings over ambiguous `NodeNext` if TS changed behavior).

Example:
```json
{
  "dependencies": {
    "langium": "1.2.0",        // non-semver: pin
    "chokidar": "^3.6.0",    // semver: allow compatible updates
    "@iconify/utils": "3.0.1" // pinned to known-good version
  },
  "peerDependencies": {
    "mermaid": "~11.7.0"     // compatible minor/patch range
  }
}
```

And for `tsconfig.json`, keep `module`/`moduleResolution` consistent with the TS version you run (e.g., `Node16`/`Node16` or `Node18`/`Node16`), rather than blindly using `NodeNext`.

---

## Use descriptive, unambiguous names

<!-- source: bazelbuild/bazel | topic: Naming Conventions | language: Java | updated: 2025-08-27 -->

Choose names that clearly communicate their purpose and avoid ambiguity or misinterpretation. Names should be self-documenting and consider what developers will wonder about at the call site.

**Key principles:**
- **Be specific over generic**: Use `isExecutableNonTestRule` instead of `isExecutableRule` when the distinction matters to callers
- **Avoid ambiguous terms**: Replace `underlying` with more precise terms like `hidden` or `server` when the context is unclear
- **Consider call site clarity**: Choose names based on what developers need to understand when using the method
- **Use descriptive constants**: Prefer `UNKNOWN_CPU_TIME` over generic `UNKNOWN` when the context matters
- **Match actual behavior**: Ensure method names like `applyInvalidation` accurately reflect what the method does rather than how it might be interpreted

**Example:**
```java
// Ambiguous - what kind of rule?
public static boolean isExecutableRule(Target target)

// Clear - specifies it excludes test rules  
public static boolean isExecutableNonTestRule(Target target)

// Vague constant
private static final long UNKNOWN = -1;

// Descriptive constant
private static final long UNKNOWN_CPU_TIME = -1;
```

This approach reduces cognitive load, prevents misunderstandings, and makes code more maintainable by ensuring names serve as clear documentation of intent.

---

## Avoid eager cache invalidation

<!-- source: bazelbuild/bazel | topic: Caching | language: Java | updated: 2025-08-27 -->

Resist the urge to eagerly invalidate cache entries unless you have definitive proof that the cached data is invalid and cannot provide value for future operations. Cache entries can still be valuable even when their associated remote artifacts have expired or been removed.

The key principle is that cache invalidation should be conservative - err on the side of keeping potentially useful cache entries rather than aggressively removing them. Even when remote cache artifacts are no longer available, the local cache entry may still save build time for actions whose outputs are never materialized.

Consider these approaches instead of eager invalidation:
- Use lazy invalidation where cache entries are only removed when they're proven to cause issues
- Implement cache validation checks (like symlink detection) to determine if cached results are still valid
- Clean up only entries that are definitively stale (like server-lifetime entries from previous instances)

Example of conservative cache management:
```java
if (actionCache != null && token != null) {
  // Don't eagerly delete - cache entry can still save build time 
  // for actions whose outputs are never materialized
  if (token.dirty) {
    actionCache.put(token.key, token.entry);
  }
}

// Only clean up definitively stale entries
actionCache.removeIf(entry -> 
  entry.getOutputFiles().values().stream()
    .anyMatch(e -> e.getExpireAtEpochMilli() == SERVER_EXPIRATION_SENTINEL));
```

This approach maximizes cache hit rates while maintaining correctness, leading to better build performance overall.

---

## prefer existence over truthiness

<!-- source: cypress-io/cypress | topic: Null Handling | language: TypeScript | updated: 2025-08-25 -->

Use explicit existence checks instead of truthiness checks when dealing with object properties, null/undefined values, or when falsy values are valid data.

Truthiness checks can cause bugs in several scenarios:
1. **Object properties containing objects/promises** - These are always truthy even when you want to check existence
2. **Falsy but valid values** - Values like `0`, `""`, or `false` that should be processed but fail truthiness checks
3. **Null vs undefined distinction** - When you need to handle both null and undefined consistently

**Examples:**

```typescript
// ❌ Bad: Promise objects are always truthy
if (fileProcessors[filePath]) {
  return fileProcessors[filePath]
}

// ✅ Good: Check for property existence
if (filePath in fileProcessors) {
  return fileProcessors[filePath]
}

// ❌ Bad: Filters out valid falsy values like "0"
return trim ? dequote(_.trim(result)) : result

// ✅ Good: Only filter out null/undefined
return trim && result != null ? dequote(_.trim(result)) : result

// ❌ Bad: Boolean true is falsy in this context check
if (keyEntry === undefined) {
  // handle undefined case
}

// ✅ Good: Explicit check avoids confusion with boolean values
if (!keyEntry) {
  // This would incorrectly trigger for boolean false
}
```

Use `in` operator for object property existence, `!= null` for null/undefined checks when falsy values are valid, and be explicit about what condition you're actually testing for.

---

## Environment variable validation

<!-- source: cypress-io/cypress | topic: Configurations | language: TypeScript | updated: 2025-08-22 -->

Always validate environment variables with proper type checking, fallback values, and defensive handling to prevent runtime failures and unexpected behavior.

Environment variables can be undefined, have incorrect types, or contain invalid values. Implement defensive validation patterns that ensure your application gracefully handles these scenarios:

```typescript
// Bad: Direct usage without validation
const timeout = +process.env.CYPRESS_VERIFY_TIMEOUT || 30000
const baseUrl = process.env.CYPRESS_DOWNLOAD_MIRROR

// Good: Defensive validation with proper fallbacks
const getVerifyTimeout = (): number => {
  const verifyTimeout = +(process.env.CYPRESS_VERIFY_TIMEOUT || 'NaN')
  
  if (_.isNumber(verifyTimeout) && !_.isNaN(verifyTimeout)) {
    return verifyTimeout
  }
  
  return 30000
}

const getBaseUrl = (): string => {
  const baseUrl = process.env.CYPRESS_DOWNLOAD_MIRROR
  
  if (!baseUrl?.endsWith('/')) {
    return baseUrl ? baseUrl + '/' : defaultBaseUrl
  }
  
  return baseUrl || defaultBaseUrl
}

// Remember: Environment variables are always strings
const forceColor = process.env.FORCE_COLOR === '0' // not === 0
```

Key principles:
- Always provide sensible default values
- Validate types and ranges for numeric environment variables  
- Remember that environment variables are always strings when passed between processes
- Use optional chaining and nullish coalescing for safer property access
- Consider implementing opt-out mechanisms for privacy-sensitive features using environment variables like `CYPRESS_CRASH_REPORTS`

---

## Options-Based API Design

<!-- source: mermaid-js/mermaid | topic: API | language: TypeScript | updated: 2025-08-22 -->

When designing/typing internal and public APIs, keep signatures tight and future-proof:

- Don’t pass parameters you don’t use. If `config` isn’t needed, remove it from the function signature (or make it optional only where truly required).
- Prefer a single options object over adding more positional parameters. This keeps the API extensible and avoids churn.
- Apply behavior consistently at the public entrypoint (e.g., preprocessing should happen inside the specific API users call, not only in constructors or other internal paths).
- Treat exported/internal types as contract surfaces: document changes and/or isolate unstable types behind dedicated entrypoints or explicit “internal/alpha” markings.

Example (extensible options object):

```ts
type ShapeOptions = {
  config?: { themeVariables: unknown };
};

export const filledCircle = (
  parent: SVG,
  node: Node,
  { config }: ShapeOptions = {}
) => {
  const themeVariables = config?.themeVariables;
  // ...render using themeVariables (or a default if absent)
};
```

Example (prefer optional/options instead of extra required positional params):

```ts
type RenderDraw = (
  text: string,
  id: string,
  version: string,
  diagramObject: Diagram,
  opts?: { error?: Error | null }
) => void;
```

Applying these standards reduces breaking changes, makes internal renderer/diagram code easier to evolve, and ensures public APIs behave predictably.

---

## meaningful test assertions

<!-- source: cypress-io/cypress | topic: Testing | language: TypeScript | updated: 2025-08-22 -->

Write tests that verify specific behavior and outcomes rather than relying on weak assertions like snapshots or generic checks. Tests should validate the actual functionality being tested, not just capture output or run without proper verification.

Instead of snapshot tests that become non-deterministic and don't validate real behavior:
```typescript
// Avoid: Weak snapshot testing
cy.findByTestId('file-match-indicator').should('exist')
```

Write tests with specific, meaningful assertions:
```typescript
// Prefer: Specific behavior verification  
cy.findByTestId('file-match-indicator').should('contain', '2 Matches')
cy.findByRole('link', { name: 'Okay, run the spec' })
  .should('have.attr', 'href', '#/specs/runner?file=src/App.cy.jsx')
```

When adding test coverage, ensure tests verify the expected functionality rather than just exercising code paths. Include assertions that validate the actual behavior users would experience, such as checking that clicking a component correctly finds matches or that spec generation produces the expected output files.

This approach creates more reliable, maintainable tests that catch real regressions and provide confidence in the system's behavior.

---

## GitHub Actions security review

<!-- source: jj-vcs/jj | topic: Security | language: Yaml | updated: 2025-08-22 -->

Always review GitHub Actions workflows for security implications before merging, particularly focusing on authentication mechanisms and credential handling. Understand what permissions like `id-token: write` grant and their potential attack vectors. Ensure secure defaults are explicitly configured, such as disabling credential persistence.

Key security considerations:
- Understand JWT token permissions and their scope: "It allows GHA actions to request a JWT token on behalf of your repository"
- Be aware of potential abuse scenarios: "Bad Guys could get a hold of it during an actual execution of this workflow"
- Explicitly disable credential persistence to prevent vulnerabilities: `persist-credentials: false`
- Use security scanning tools to identify configuration issues

When implementing new authentication mechanisms, ensure team members understand the security model and document any special permissions required for maintainer approval.

---

## Pin actions to commits

<!-- source: jj-vcs/jj | topic: CI/CD | language: Yaml | updated: 2025-08-22 -->

Use specific commit hashes instead of version tags when referencing GitHub Actions in CI/CD workflows. Version tags can be moved or updated, potentially introducing security vulnerabilities or breaking changes, while commit hashes are immutable and provide reproducible builds.

Replace version tags like `@v4` or `@v3` with the full commit hash:

```yaml
# Instead of:
- uses: actions/checkout@v4
- uses: DeterminateSystems/determinate-nix-action@v3

# Use:
- uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8
- uses: DeterminateSystems/determinate-nix-action@b7303d63f88908d15f0bcb207e60b3a0ea7f1712
```

This practice enhances security by preventing supply chain attacks where malicious actors could update the code behind a version tag, and ensures reproducible builds by guaranteeing the exact same action code runs every time.

---

## Use proper synchronization primitives

<!-- source: nrwl/nx | topic: Concurrency | language: TypeScript | updated: 2025-08-20 -->

When implementing concurrent operations, always use appropriate synchronization mechanisms and ensure all asynchronous code paths complete properly. This includes specifying explicit timing parameters, using efficient blocking primitives, and guaranteeing promise resolution in all execution branches.

Key practices:
1. **Explicit timing**: Always specify delay values in timing functions like setTimeout() with clear documentation of the reasoning
2. **Efficient synchronization**: Use proper blocking primitives like Atomics.wait() instead of busy polling when waiting for other processes
3. **Complete async paths**: Ensure all code branches in asynchronous operations properly resolve or reject promises

Example of proper synchronization:
```typescript
// Bad: Missing delay parameter
setTimeout(() => {
  this.sendToDaemonViaQueue(msg).then(res, rej);
});

// Good: Explicit delay with reasoning
setTimeout(() => {
  // Wait 100ms for daemon to finish shutting down
  this.sendToDaemonViaQueue(msg).then(res, rej);
}, 100);

// Good: Efficient blocking with Atomics.wait
while (!projectGraphCache && Date.now() - startTime < maxWaitTime) {
  Atomics.wait(sharedArray, 0, 0, pollInterval);
  projectGraphCache = readProjectGraphCache(minimumComputedAt);
}

// Good: Promise resolved in all paths
this.childProcess.onExit((message) => {
  this.isAlive = false;
  const code = messageToCode(message);
  this.childProcess.cleanup();
  this.exitCallbacks.forEach((cb) => cb(code));
  res({ success: false, code, terminalOutput: this.terminalOutput }); // Don't forget this!
});
```

This prevents race conditions, ensures predictable timing behavior, and maintains proper async operation completion.

---

## surface failures early

<!-- source: mermaid-js/mermaid | topic: Error Handling | language: JavaScript | updated: 2025-08-19 -->

Make rendering/runtime failures observable instead of silently tolerated.

Apply two concrete rules:
1) **Cover failure-prone inputs in tests**: when your code parses special syntaxes (e.g., `@{ ... }` blocks), add variations that stress spacing/quoting/formatting so broken input is exercised.

2) **Don’t swallow async dependency errors**: if loading external assets/fonts fails, avoid `try/catch` that only logs. Either let the promise reject (so Cypress/test fails) or rethrow after adding context.

Example (preferred: errors surface and tests fail):
```js
async function contentLoaded() {
  await loadFontAwesomeCSS();
  await Promise.all(Array.from(document.fonts, (font) => font.load()));
}
```

Example (log *and* propagate):
```js
const contentLoaded = async () => {
  try {
    await loadFontAwesomeCSS();
    await Promise.all(Array.from(document.fonts, (font) => font.load()));
  } catch (err) {
    console.error('Error loading fonts', err);
    throw err;
  }
};
```

Outcome: developers get a clear stack/error when something breaks, and tests/CI catch edge-case syntax issues instead of only validating the happy path.

---

## prefer simple readable code

<!-- source: bazelbuild/bazel | topic: Code Style | language: Other | updated: 2025-08-18 -->

Favor simple, readable implementations over complex or overly abstracted solutions. This includes eliminating code duplication through better function design, simplifying complex expressions, and using standard library functions instead of custom helpers.

Key practices:
- **Eliminate duplication**: Instead of duplicating long function calls, use loops or extend existing functions with additional parameters
- **Simplify expressions**: Break down complex regex, conditionals, or string manipulations into more readable forms
- **Use standard libraries**: Prefer established library functions (like `paths.basename` or `AsciiStrToUpper`) over custom helper functions
- **Question complexity**: Ask whether complex class hierarchies or abstractions are truly necessary

Example of simplification:
```starlark
# Instead of duplicating calls:
if generate_no_pic_action:
  _create_helper(..., use_pic=False)
if generate_pic_action:
  _create_helper(..., use_pic=True)

# Use a loop:
use_pic_values = []
if generate_no_pic_action:
  use_pic_values.append(False)
if generate_pic_action:
  use_pic_values.append(True)
for use_pic in use_pic_values:
  _create_helper(..., use_pic=use_pic)
```

This approach reduces maintenance burden, improves readability, and makes code easier to understand for future developers.

---

## Choose efficient data structures

<!-- source: microsoft/terminal | topic: Algorithms | language: Other | updated: 2025-08-18 -->

Select data structures and types that optimize for both memory usage and computational efficiency. Avoid unnecessary copies, use appropriately sized types, and consider the performance characteristics of your choices.

Key principles:
- Use immutable, shared data structures when possible instead of per-instance copies (e.g., making `_argDescriptors` lazy-initialized constants rather than mutable copies per instance)
- Choose appropriately sized types for your data (e.g., `IndexType` instead of `size_t` for color indices, `char32_t` instead of `int` for character data)
- Avoid wasteful operations like unnecessary vector merging when simpler alternatives exist
- Use containers designed for your use case (`std::vector<int>` for numeric arrays rather than `std::basic_string<int>`)
- Leverage transparent hash/equality types for better lookup performance in hash containers

Example of inefficient vs efficient approach:
```cpp
// Inefficient: Creates new vector every time
std::vector<ArgDescriptor> GetDescriptors() {
    std::vector<ArgDescriptor> merged;
    for (const auto desc : thisArgs) {
        merged.push_back(desc);  // Unnecessary copying
    }
    return merged;
}

// Efficient: Use shared immutable data
static const auto& GetDescriptors() {
    static const auto descriptors = InitializeDescriptors();
    return descriptors;  // Return reference to shared data
}
```

Consider the computational complexity and memory footprint of your data structure choices, especially for frequently accessed or large-scale data.

---

## validate feature configurations

<!-- source: bazelbuild/bazel | topic: Configurations | language: Other | updated: 2025-08-18 -->

Always validate that required features are enabled before using feature-dependent functionality. Feature flags should be the primary condition for enabling code paths, not the presence of related data or parameters.

When implementing feature-dependent behavior:
1. Check feature enablement first, regardless of data availability
2. Provide clear error messages when required features are missing
3. Use feature flags to gate potentially disruptive changes
4. Fail early rather than allowing silent failures or unexpected behavior

Example of proper feature validation:
```starlark
# Good: Check feature first, regardless of data presence
if feature_configuration.is_enabled("cpp_modules"):
    _create_cc_compile_actions_with_cpp20_module(...)
    return

# Also good: Validate required features with clear error messages  
def _check_cpp20_module(ctx, feature_configuration):
    if len(ctx.files.module_interfaces) > 0 and not cc_common.is_enabled(
        feature_configuration = feature_configuration,
        feature_name = "cpp20_module",
    ):
        fail("to use C++20 Modules, the feature cpp20_module must be enabled")

# Avoid: Making feature enablement dependent on data availability
if module_interfaces_sources and feature_configuration.is_enabled("cpp_modules"):
```

This approach ensures consistent behavior, prevents silent failures, and makes feature dependencies explicit and debuggable.

---

## explicit null checks

<!-- source: bazelbuild/bazel | topic: Null Handling | language: Other | updated: 2025-08-18 -->

Use explicit null/undefined checks instead of methods that silently handle missing values. When you expect a value to be present, use access patterns that will fail fast if the value is missing rather than returning default values or silently continuing.

**Prefer explicit checks that fail on missing values:**
- Use dictionary `[key]` instead of `get(key)` when the key must be present
- Use `!= None` instead of truthy checks when distinguishing null from empty collections
- Add bounds checking before accessing array/string elements

**Example from code review:**
```python
# Instead of using .get() which silently returns None:
ddi_file = source_to_ddi_file_map.get(source_artifact)

# Use direct access that fails if key is missing:
ddi_file = source_to_ddi_file_map[source_artifact]

# For collections, distinguish None from empty:
if lib.pic_objects != None:  # Not just: if lib.pic_objects:
    # Handle non-null collection (may be empty)
```

This approach makes your code more robust by catching bugs early when values are unexpectedly missing, rather than allowing silent failures that can be harder to debug later.

---

## Use precise terminology

<!-- source: nrwl/nx | topic: Naming Conventions | language: Markdown | updated: 2025-08-18 -->

Always use specific, accurate terminology rather than vague or generic terms when naming sections, referencing products, or writing documentation. Ensure grammatical correctness and technical precision in all naming contexts.

When referencing specific products or technologies, use their official names rather than broad categories. For example, use "JetBrains IDEs" instead of "IDEA based editors" when referring to IntelliJ, WebStorm, and similar tools. Similarly, maintain proper article usage and grammatical structure, such as "the Angular CLI" rather than "Angular CLI" when used as a subject.

This principle applies to:
- Section headers and documentation titles
- Product and technology references  
- Variable and method names in code
- Comments and technical writing

Example from documentation:
```markdown
// Vague and imprecise
### VS Code / Cursor Setup

// Precise and accurate  
### VS Code Setup
### Cursor / JetBrains IDEs Setup
```

Precise terminology reduces ambiguity, improves clarity, and demonstrates attention to detail in both code and documentation.

---

## Comprehensive contextual error handling

<!-- source: microsoft/playwright | topic: Error Handling | language: Other | updated: 2025-08-18 -->

Implement thorough error handling that goes beyond basic logging and provides contextually accurate, actionable error messages. Error handling should include proper propagation, recovery mechanisms where appropriate, and messages that reflect the actual system state and available options.

Avoid minimal error handling that only logs errors:
```javascript
// Inadequate - just logs and continues
socket.on('error', (error) => console.log('socket error from wrapper', error));
```

Instead, implement comprehensive error handling with context-aware messaging:
```javascript
// Better - proper error handling with context
socket.on('error', (error) => {
    console.error('Socket connection failed:', error.message);
    process.exit(1); // or appropriate recovery mechanism
});

// Context-aware error messages
if (!(await fs.promises.stat(executable)).isFile()) {
    const packageManager = detectPackageManager(); // Use actual detected manager
    throw new Error(`Executable does not exist. Did you update Playwright recently? Make sure to run ${packageManager} playwright install webkit-wsl`);
}
```

Error messages should be accurate to the current system context and provide specific, actionable guidance rather than generic assumptions about user environment or tooling.

---

## Minimize reference counting overhead

<!-- source: microsoft/terminal | topic: Performance Optimization | language: Other | updated: 2025-08-16 -->

Avoid unnecessary reference counting operations that can impact performance, especially in frequently called code paths. Use move semantics, appropriate pointer types, and efficient parameter passing to reduce AddRef/Release churn.

Key strategies:
1. **Use raw pointers when lifetime is guaranteed**: Replace `std::shared_ptr` with raw pointers when the object lifetime is managed by a parent that outlives the consumer
2. **Prefer move semantics for WinRT types**: Take WinRT parameters by value and use `std::move` when assigning to members to avoid extra AddRef/Release cycles
3. **Avoid expensive WinRT collections**: Use standard containers like `std::vector` internally and wrap with `winrt::multi_threaded_vector` only when needed for WinRT interfaces

Example transformations:
```cpp
// Before: Unnecessary shared_ptr overhead
void Constructor(const std::shared_ptr<Cache>& cache) : _cache(cache) {}

// After: Raw pointer when lifetime is guaranteed
void Constructor(Cache* cache) : _cache(cache) {}

// Before: Extra AddRef/Release on assignment  
Constructor(const IVector<T>& items) : _items(items) {}

// After: Move to avoid reference count churn
Constructor(IVector<T> items) : _items(std::move(items)) {}
```

This optimization is particularly important for frequently instantiated objects and hot code paths where reference counting overhead can accumulate significantly.

---

## Use standard API abstractions

<!-- source: bazelbuild/bazel | topic: API | language: Other | updated: 2025-08-15 -->

Prefer established, type-safe abstractions over primitive types or direct property access when designing APIs. This improves maintainability, enables future extensibility, and provides better developer experience.

Use standard library types and framework-provided abstractions instead of custom primitives:
- Use `google.protobuf.Duration` instead of `int64` millisecond fields
- Use `std::string_view` instead of `const char*` for string parameters
- Use framework argument builders instead of direct property access like `.path`

Example improvements:
```cpp
// Instead of:
static bool IsValidEnvName(const char* p) { ... }

// Use:
static bool IsValidEnvName(std::string_view name) { ... }
```

```proto
// Instead of:
int64 critical_path_time_in_ms = 4;

// Use:
google.protobuf.Duration critical_path_time = 4;
```

These abstractions often provide additional functionality (like automatic path mapping, timezone handling, or memory efficiency) and make APIs more robust and future-proof.

---

## Ensure informative log messages

<!-- source: nrwl/nx | topic: Logging | language: TypeScript | updated: 2025-08-15 -->

Log messages should be clear, informative, and include specific details to help users understand what is happening. Avoid vague messages that could cause confusion, and ensure proper stream handling to prevent garbled output in concurrent scenarios.

When logging status or waiting messages, include the specific values or URLs being referenced:

```typescript
// Bad - vague and potentially confusing
console.log('Waiting for registry configuration to change from default...');

// Good - includes specific information
console.log('Waiting for registry configuration to change from https://registry.npmjs.org/...');
```

For concurrent processes that write to stdout/stderr, implement proper stream management to prevent output corruption:

```typescript
// Use LineAwareStream or similar mechanisms to ensure complete lines
task.childProcess.stdout?.on('data', (data) => {
  globalLineAwareStream.write(data, task.id);
});
```

This prevents garbled output when multiple processes are writing simultaneously and ensures logs remain readable and useful for debugging.

---

## Document network limitations

<!-- source: microsoft/playwright | topic: Networking | language: Markdown | updated: 2025-08-15 -->

When documenting network-related features, clearly specify compatibility constraints, browser limitations, and potential side effects. This is especially critical for experimental features or those with platform-specific restrictions.

Always include:
- Explicit browser/platform compatibility information
- Warnings for experimental features that may change
- Known limitations and their impact on functionality
- Potential side effects (e.g., CORS implications, header modifications)

Example:
```ts
// Good: Clear limitations and warnings
/**
 * Mocking proxy is **experimental** and subject to change.
 * Limitations:
 * - Extra headers will affect CORS preflight requests
 * - Server requests not triggered by browser won't be routed
 * - Only works with persistent browser contexts
 */
export default defineConfig({
  use: { mockingProxy: true }
});
```

This prevents user confusion, reduces support burden, and helps developers make informed decisions about feature adoption.

---

## Python syntax consistency

<!-- source: microsoft/playwright | topic: Naming Conventions | language: Markdown | updated: 2025-08-15 -->

Ensure Python code follows proper naming conventions and syntax rules. Use snake_case for variable and parameter names instead of camelCase, and use capitalized boolean literals (True/False) instead of lowercase variants from other languages.

This addresses common issues when adapting code examples from other languages or when developers switch between different programming contexts. Both naming and boolean literal consistency are essential for Python code correctness and readability.

Example:
```python
# Incorrect
context = await browser.new_context(
  isMobile=false
)

# Correct  
context = await browser.new_context(
  is_mobile=False
)
```

---

## Specify algorithmic scope precisely

<!-- source: astral-sh/ty | topic: Algorithms | language: Markdown | updated: 2025-08-14 -->

When documenting changes to algorithms, data structures, or computational approaches, explicitly identify the specific components affected rather than using vague or generic descriptions. This includes naming exact data structure classes, clarifying the scope and limitations of algorithmic improvements, and using precise technical terminology.

For example, instead of writing "improve subscript narrowing for safe mutable classes", specify the exact classes: "improve subscript narrowing for `collections.ChainMap`, `collections.Counter`, `collections.deque` and `collections.OrderedDict`". Similarly, when describing algorithmic support, clarify what is and isn't included - such as noting that recursive type alias support is limited to "non-generic recursive type aliases that use the `type` statement" rather than implying full recursive type support.

This precision helps developers understand exactly which algorithms and data structures are affected, prevents misconceptions about capabilities, and enables more targeted testing and usage of the improvements.

---

## Configuration documentation clarity

<!-- source: cypress-io/cypress | topic: Configurations | language: Markdown | updated: 2025-08-14 -->

Ensure configuration documentation, setup instructions, and changelogs use precise, clear language with proper technical terminology. Avoid ambiguous words like "sometimes" or "generally" that create uncertainty. Use correct capitalization for technical terms (e.g., "Node.js" not "Node", "CommonJS/ESM" not "commonjs/ESM"). Remove redundant words and fix grammatical errors that can confuse users.

Examples of improvements:
- "be default" → "by default"
- "Node for commonjs/ESM" → "Node.js for CommonJS/ESM" 
- "Sometimes, when using nvm..." → "When using nvm..."
- "no longer be supported" → "no longer supported"

Configuration documentation should provide definitive, tested instructions rather than vague guidance, as users rely on this information to set up their development environments correctly.

---

## API documentation clarity

<!-- source: astral-sh/ty | topic: API | language: Markdown | updated: 2025-08-14 -->

Ensure API documentation, including changelogs and feature descriptions, prioritizes user understanding over implementation details. Write descriptions that explain what users can expect from the API behavior rather than how it's technically implemented. Avoid redundant information when context is already established (e.g., don't repeat "language server feature" under a "Server" section). Provide proper references and links to specifications or external documentation when mentioning technical concepts.

Example improvements:
- Instead of: "Implement non-stdlib stub mapping for classes and functions"
- Write: "Prefer the runtime definition, not the stub definition, on a go-to-definition request for a class or function"

- Instead of: "Add semantic token support for more identifiers"  
- Write: "Add [semantic token](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_semanticTokens) support for more identifiers"

This approach makes API documentation more accessible to users who need to understand functionality and behavior, not internal implementation choices.

---

## API clarity over convenience

<!-- source: microsoft/terminal | topic: API | language: Other | updated: 2025-08-14 -->

When designing APIs, prioritize clarity and self-documentation over implementation convenience. Choose interface patterns that make the code's intent immediately obvious to consumers and debuggers.

For data access APIs, prefer descriptive string-based keys over numerical indexing when the performance impact is acceptable. As noted in code review discussions: "If you were to debug it and see '5' it's not immediately clear what you want, whereas with 'windowTitle' you kind of know already."

For interface definitions, avoid unnecessary annotations that add complexity without benefit. Only use attributes like `[default_interface]` when the runtime class has no other interface and no identifying characteristics.

Example of preferred approach:
```cpp
// Instead of numerical indexing:
GetArgAt(5)  // Unclear what argument this represents

// Prefer descriptive access:
GetArgByName("windowTitle")  // Self-documenting intent

// Or return descriptors that include names:
auto descriptor = GetArgDescriptorAt(index);  // descriptor.Name provides context
```

This principle applies broadly to API design: choose patterns that make debugging easier and code more self-documenting, even if they require slightly more implementation effort.

---

## optimize algorithmic choices

<!-- source: microsoft/terminal | topic: Algorithms | language: C++ | updated: 2025-08-13 -->

Choose efficient algorithms and data structures to improve performance and reduce computational overhead. This involves selecting appropriate containers, avoiding unnecessary operations, and leveraging language features for optimization.

Key optimization strategies:
- **Use specialized containers**: Prefer `til::static_map` over `std::unordered_map` for compile-time initialization, or `wil::to_vector` for collection cloning
- **Leverage return values**: Use the return value of operations like `insert()` instead of separate `contains()` + `insert()` calls
- **Apply move semantics**: Use `std::move` when transferring ownership, especially with expensive objects like `std::filesystem::path`
- **Choose better algorithms**: Replace expensive operations like `lstrcmpiW` with more efficient alternatives like ICU functions for Unicode handling
- **Avoid unnecessary copies**: Be careful with reference binding to prevent breaking return value optimization

Example of inefficient vs optimized approach:
```cpp
// Inefficient: separate contains + insert
if (!state->DismissedBadges->contains(badgeId)) {
    state->DismissedBadges->insert(badgeId);
    inserted = true;
}

// Optimized: use insert return value
auto [iter, inserted] = state->DismissedBadges->insert(badgeId);
```

For mathematical computations, choose appropriate distance metrics - use squared Euclidean distance `r*r + g*g + b*b` instead of Manhattan distance `abs(r) + abs(g) + abs(b)` for color comparisons to better represent perceptual differences.

---

## Safe null handling patterns

<!-- source: microsoft/terminal | topic: Null Handling | language: Other | updated: 2025-08-13 -->

Always use consistent and safe patterns when dealing with potentially null or undefined values. This includes using safe casting methods, explicit null checks, proper initialization, and immutable variables after validation.

Key practices:
1. **Consistent safe casting**: Use `try_as<T>()` instead of `as<T>()` to avoid runtime exceptions when casting might fail
2. **Explicit null validation**: Check for null/empty values before using them, especially in serialization contexts
3. **Proper initialization**: Initialize all member variables to prevent undefined behavior
4. **Immutable variables after checks**: Use `const auto` when storing results of null checks to prevent accidental modification

Example from the codebase:
```cpp
// Inconsistent - uses try_as in one place but as in another
if (const auto newTermArgs = _ContentArgs.try_as<NewTerminalArgs>())
{
    return newTermArgs->GetArgCount() + gsl::narrow<uint32_t>(_argDescriptors.size());
}
// Should also use try_as here for consistency
return _ContentArgs.as<NewTerminalArgs>()->GetArgDescriptorAt(index - additionalArgCount);

// Better approach - consistent safe casting
if (const auto newTermArgs = _ContentArgs.try_as<NewTerminalArgs>())
{
    return newTermArgs->GetArgDescriptorAt(index - additionalArgCount);
}

// Proper null handling in serialization
if (json.isNull())
{
    return MediaResource::FromString(L"");
}

// Proper initialization to prevent undefined behavior
UINT _systemMenuNextItemId = 0;  // Instead of leaving uninitialized
```

This pattern prevents runtime crashes, undefined behavior, and makes code more predictable and maintainable.

---

## Prioritize documentation clarity

<!-- source: microsoft/playwright | topic: Documentation | language: Markdown | updated: 2025-08-12 -->

Documentation should prioritize clarity and actionable guidance over comprehensive coverage. Organize content logically by placing the most relevant information first, provide clear recommendations on preferred approaches, and avoid unnecessary complexity or redundant details that don't add value.

Key principles:
- Structure content to guide users toward the best practices (e.g., "you should use config option instead" rather than just explaining alternatives)
- Remove redundant information that can diverge from authoritative sources
- Focus on essential information and avoid "unnecessary details for the default mode"
- Provide clear, actionable guidance that helps users "immediately understand what to do"

Example of good practice:
```markdown
:::note
The `context.tracing` API records different information than the automatic tracing enabled through [Playwright Test configuration](https://playwright.dev/docs/api/class-testoptions#test-options-trace). For most use cases, you should use the configuration option instead as it captures both browser operations and test assertions.
:::
```

This approach ensures documentation serves as an effective guide rather than just a comprehensive reference, helping users make informed decisions quickly.

---

## testing best practices

<!-- source: microsoft/playwright | topic: Testing | language: Markdown | updated: 2025-08-12 -->

Choose testing methods, configurations, and approaches that prioritize user experience and reliability over theoretical completeness. Consider the practical needs of your development team and testing environment when making decisions.

Key principles:
- **Prefer user-friendly options**: Choose testing flags and commands that developers actually use. For example, prefer `--ui` over `--list` for better developer experience when exploring tests.
- **Select appropriate assertion methods**: Use `toEqual` for most equality checks rather than `toStrictEqual`, as it provides sufficient validation without unnecessary strictness.
- **Configure based on context**: Adapt testing configurations to your specific environment. For test sharding, `round-robin` may provide better distribution than `partition` depending on your test organization. For flaky test handling, consider stricter settings in CI environments.
- **Balance stability with flexibility**: When choosing between testing approaches, consider both immediate usability and long-term maintenance. Evaluate whether more complex solutions actually solve real problems your team faces.

Example of contextual configuration:
```js
// playwright.config.ts
export default defineConfig({
  // Stricter flaky test handling in CI
  failOnFlakyTests: !!process.env.CI,
  // Better test distribution for organized test suites
  shardingMode: 'round-robin'
});
```

This approach ensures your testing setup serves your team's actual workflow rather than following rigid theoretical ideals.

---

## Invariant-Preserving Graph Algorithms

<!-- source: mermaid-js/mermaid | topic: Algorithms | language: JavaScript | updated: 2025-08-08 -->

When a graph/geometry algorithm is used recursively (or downstream computations depend on its shape/metrics), don’t patch symptoms. Preserve invariants end-to-end:

- Fix the algorithmic root cause: if label/point alignment breaks due to path generation (e.g., curve smoothing not passing through control points), change the path/curve strategy (e.g., use ELK-style “nice corners”/corner treatment) so label positioning assumptions remain true.
- Propagate only safe configuration: when setting subgraph graph params, copy only the layout invariants you intend (e.g., ranksep/nodesep). Avoid copying unrelated spacing fields that can shift layout (e.g., marginy).
- Use robust data structures for algorithm state: prefer `Map` over plain objects for wrapper/global state (descendants/parents/cluster DB) to avoid key collisions and make updates predictable.

Example (subgraph config propagation):
```js
// In recursive render for subgraphs
const { ranksep, nodesep } = graph.graph();
node.graph.setGraph({
  ...node.graph.graph(),
  ranksep,
  nodesep,
});
```

Example (wrapper state as Map):
```js
export let clusterDb = new Map();
let descendants = new Map();
let parents = new Map();

export const clear = () => {
  clusterDb = new Map();
  descendants = new Map();
  parents = new Map();
};
```

---

## Specify security requirements

<!-- source: microsoft/terminal | topic: Security | language: Other | updated: 2025-08-08 -->

Always explicitly declare security requirements and provide clear security guidance in both configuration files and user-facing content. When operations require elevated privileges, specify the security context to ensure proper UAC prompting. When features have security implications, include explanatory text to help users make informed decisions.

For configuration files requiring elevation:
```yaml
- resource: Microsoft.Windows.Developer/DeveloperMode
  directives:
    description: Enable Developer Mode
    allowPrerelease: true
    securityContext: elevated  # Required for UAC prompting
```

For user-facing security features, provide context about the security implications:
```xml
<data name="Globals_WarnAboutMultiLinePaste.HelpText" xml:space="preserve">
  <value>If your shell does not support "bracketed paste" mode, we recommend setting this to "Always" for security reasons.</value>
</data>
```

This practice ensures that security requirements are transparent to both the system (for proper privilege handling) and users (for informed decision-making), reducing the risk of security misconfigurations or unintended security bypasses.

---

## Structure documentation logically

<!-- source: astral-sh/ty | topic: Documentation | language: Markdown | updated: 2025-08-07 -->

Organize documentation sections and content to match user mental models and workflows, not internal technical implementation details. Use descriptive, specific section names instead of generic ones like "Other changes" or overly technical terms. Present information in the order users will encounter or need it, prioritizing common use cases before advanced configuration options.

For example, when documenting configuration options, lead with default behavior that most users will experience, then explain override mechanisms:

```markdown
# Good: User-centric organization
## Python environment

By default, ty searches for a `.venv` folder in the project root. If the `VIRTUAL_ENV` environment variable is set, ty will use that path instead.

The Python environment can also be explicitly specified using the `--python` flag...

# Better section naming
## Typing semantics and features
(instead of "Other changes")

## Logging options  
(instead of "Initialization options" when content is logging-specific)
```

Consider future extensibility when naming sections - avoid overly specific names that may need renaming as features expand. Structure content to minimize cognitive load by following the user's natural workflow and decision-making process.

---

## Use semantic naming

<!-- source: microsoft/terminal | topic: Naming Conventions | language: Other | updated: 2025-08-06 -->

Names should clearly communicate their purpose, type, and behavior to improve code maintainability and accessibility. Avoid misleading or ambiguous terminology that can confuse developers or users.

Key principles:
- **Indicate type and purpose**: Variable names should reflect both what they contain and how they're used. For example, prefer `ProposedShortcutActionName` over `ProposedShortcutAction` when the value is specifically a string.
- **Avoid misleading terms**: Don't use names like `required` for validation checks when it's not actually a boolean requirement flag.
- **Provide accessibility context**: UI elements must have meaningful names for screen readers. Set `AutomationProperties.Name` with descriptive text rather than leaving buttons to be read as just "button".
- **Prefer positive naming**: Use `ScrollToZoom` instead of `DisableMouseZoom` to avoid double negatives and improve clarity.
- **Follow consistent capitalization**: Use sentence case for UI text ("Split pane down" not "Split Pane Down") and maintain consistency across similar elements.

Example of improved naming:
```cpp
// Before: misleading parameter name
#define DECLARE_ARGS(type, name, jsonKey, required, ...) 
// 'required' is actually a validation expression, not a boolean

// After: clearer parameter name  
#define DECLARE_ARGS(type, name, jsonKey, validation, ...)
// 'validation' clearly indicates this is a validation expression

// Before: unclear type
VIEW_MODEL_OBSERVABLE_PROPERTY(IInspectable, ProposedShortcutAction);

// After: type-indicating name
VIEW_MODEL_OBSERVABLE_PROPERTY(IInspectable, ProposedShortcutActionName);
```

This approach reduces cognitive load, improves accessibility, and makes code self-documenting.

---

## Configuration documentation clarity

<!-- source: astral-sh/ty | topic: Configurations | language: Markdown | updated: 2025-08-06 -->

Configuration documentation should be precise, specific, and include helpful context for users. Avoid vague or ambiguous language that could lead to misunderstanding of how settings behave.

Key principles:
- Use specific, descriptive language rather than generic terms
- Explain edge cases and special behaviors explicitly
- Include examples that illustrate the actual behavior
- Add context for beginners who may not be familiar with concepts
- Clarify when behavior differs from user expectations

For example, instead of writing:
```
Paths passed explicitly are checked even if they are otherwise ignored by an exclude or ignore file.
```

Write:
```
Paths that are passed as positional arguments to `ty check` are included even if they would otherwise be ignored through `exclude` filters or an ignore-file.
```

Similarly, when explaining pattern matching behavior, be explicit about anchoring:
```
Include patterns are anchored: The pattern `src` only includes `<project_root>/src` but not something like `<project_root>/test/src`. To include any directory named `src`, use the `**/src` prefix match.
```

This approach helps users understand exactly how configuration options will behave in their specific use cases and reduces confusion about expected vs. actual behavior.

---

## comprehensive test coverage

<!-- source: microsoft/playwright | topic: Testing | language: TypeScript | updated: 2025-08-06 -->

Tests should be comprehensive and cover edge cases, complete scenarios, and use specific assertions rather than generic checks. When writing tests, include multiple test cases that validate different states, use precise count assertions instead of simple visibility checks, and ensure all relevant interactions are tested.

For example, instead of just checking visibility:
```ts
// Weak test
await expect(codeSnippets.first()).toBeVisible();

// Better test with specific counts
await expect(codeSnippets).toHaveCount(3);
await toggleCheckbox.click();
await expect(codeSnippets).toHaveCount(0);
```

When testing complex scenarios, include comprehensive cases:
```ts
// Simple test
await page.setContent(`<div inert><button>Second</button></div>`);

// More comprehensive test
await page.setContent(`
  <div aria-hidden="true"><button>First</button></div>
  <div inert><button>Second</button></div>
  <button>Third</button> <!-- not hidden for comparison -->
`);
await expect(page.getByRole('button')).toHaveCount(1); // only Third is visible
```

Always test edge cases like whitespace handling, empty states, and boundary conditions. Include tests for all relevant UI interactions such as expansion/collapse, toggling, and state changes.

---

## Use descriptive identifiers

<!-- source: microsoft/terminal | topic: Naming Conventions | language: C++ | updated: 2025-08-05 -->

Choose clear, self-documenting names for variables, methods, parameters, and properties that explicitly convey their purpose and context. Avoid ambiguous or generic names that require additional context to understand.

Key principles:
- **Method names should include context**: Prefix methods with their domain (e.g., `_OnTabClick` instead of `_OnClick`)
- **Avoid magic parameters**: Replace boolean flags with descriptive method names (e.g., `SendKeyDownEvent()` instead of `SendKeyEvent(vkey, scanCode, flags, true)`)
- **Use meaningful parameter types**: Prefer enums over indices or magic numbers for better type safety and clarity
- **Variable names should reflect their actual content**: Use names that match the data type and purpose (e.g., `charSizeInDips` vs `charSizeInPixels`)
- **Property names should be specific**: Make property change notifications explicit about what changed

Example improvements:
```cpp
// Instead of:
_terminal->SendKeyEvent(vkey, scanCode, flags, true);
tabViewItem.PointerReleased({ this, &TerminalPage::_OnClick });

// Use:
_terminal->SendKeyDownEvent(vkey, scanCode, flags);
tabViewItem.PointerReleased({ this, &TerminalPage::_OnTabClick });

// Instead of:
double PaddingValueFromIndex(const winrt::hstring& paddingString, uint32_t paddingIndex)

// Use:
double PaddingValueFromIndex(const winrt::hstring& paddingString, PaddingDirection direction)
```

This approach reduces cognitive load, makes code self-documenting, and prevents misuse of APIs by making intent explicit through naming.

---

## explicit undefined checks

<!-- source: microsoft/playwright | topic: Null Handling | language: TypeScript | updated: 2025-08-05 -->

Always use explicit checks for undefined values and return appropriate nullable types instead of relying on implicit conversions or unsafe type assertions. Use modern JavaScript equality checks and proper TypeScript utility types for null safety.

When a function might not have a value to return, use `undefined` as the return type and check explicitly:

```typescript
// Good: Explicit undefined check and nullable return type
export function formatProtocolParam(params: Record<string, string> | undefined, alternatives: string): string | undefined {
  if (!params)
    return undefined;
  
  if (params[name] !== undefined)
    return params[name];
}

// Good: Use modern equality check
if (a.description === undefined) {
  // handle undefined case
}

// Good: Use proper TypeScript utility types
type HtmlReportOpenOption = NonNullable<Options['open']>;

// Avoid: Using 'any' when 'unknown' provides better type safety
async setFileChooserInterceptedBy(enabled: boolean, by: unknown): Promise<void> {
```

This approach prevents null reference errors, makes code intentions explicit, and leverages TypeScript's type system for compile-time safety rather than relying on runtime type coercion.

---

## Document implementation rationale

<!-- source: microsoft/terminal | topic: Documentation | language: C++ | updated: 2025-08-05 -->

Add comments that explain the reasoning behind non-obvious code decisions, technical constraints, or complex logic, while avoiding over-documentation of self-evident functionality. Focus on the "why" rather than the "what" - document implementation choices that future developers (including yourself) might need to rediscover.

Examples of good rationale documentation:
- Complex conditional logic: "// An icon path is considered an emoji if it contains a zero-width joiner (U+200D) or ends with a Unicode Variation Selector"
- Implementation decisions: "// We create temporary hstrings here to avoid deep copying the entire text in the no-match case"
- Technical constraints: "// BODGY - The XAML compiler emits a boxed int32, but the dependency property expects a boxed FontWeight"

Avoid over-documenting obvious boolean returns or simple getters. Instead of "// Returns: true if successful, false otherwise", prefer concise descriptions like "// indicates the operation succeeded" when the return value needs explanation at all.

---

## Implement defensive validation

<!-- source: microsoft/terminal | topic: Error Handling | language: C++ | updated: 2025-08-04 -->

Always validate inputs, check boundaries, and avoid relying on undocumented API behavior or assumptions about how functions handle edge cases. When dealing with potentially null or invalid data, implement explicit checks rather than assuming the API will behave consistently across all scenarios.

Key practices:
- Don't assume APIs preserve or destroy values on failure - use fallback values instead
- Validate parameters before passing them to functions, especially when null could cause issues
- Check array/buffer boundaries before accessing elements
- Skip or handle invalid entries gracefully rather than processing them blindly

Example from the codebase:
```cpp
// Instead of assuming SystemParametersInfoW preserves the value on failure
unsigned int hoverTimeoutMillis{ 400 };
if (FAILED(SystemParametersInfoW(SPI_GETMOUSEHOVERTIME, 0, &hoverTimeoutMillis, 0)))
{
    hoverTimeoutMillis = 400; // Explicit fallback value
}

// Validate before processing
if (!settingsModelEntries)
{
    return single_threaded_observable_vector<Editor::NewTabMenuEntryViewModel>(std::move(result));
}

// Check boundaries to prevent crashes
if (iter.Pos() < _selection->start || iter.Pos() > _selection->end)
{
    // Safe to proceed with operation
}
```

This approach prevents crashes, undefined behavior, and makes code more robust by not relying on implementation details that may change or vary across different environments.

---

## Add comprehensive explanatory comments

<!-- source: microsoft/terminal | topic: Documentation | language: Other | updated: 2025-08-04 -->

When code involves complex relationships between multiple components or non-obvious usage patterns, add comprehensive explanatory comments that consolidate key information in one accessible location. This is especially important for files with multiple structs, classes, or APIs that work closely together.

The comment should explain:
- Relationships and responsibilities between components
- Differences between similar-looking members or methods
- How to properly use the APIs or objects
- What the code enables or prevents

Example for a header file with multiple related structs:
```cpp
/*
 * Media Resource Management System
 * 
 * This file contains structs that work together to handle media resources:
 * - MediaResource: Represents a media file with both original and resolved paths
 *   - 'ok' indicates if the resource was found, 'resolved' indicates if path resolution succeeded
 *   - 'value' is the original path, 'resolvedValue' is the absolute/canonical path
 * - MediaResourceManager: Handles loading and caching of MediaResource objects
 * 
 * Usage: Create MediaResource objects through MediaResourceManager.load() to ensure
 * proper path resolution and caching. Direct construction bypasses validation.
 */
```

Avoid scattering this information across PR descriptions, comments, or other files. Centralize it where developers will naturally look when working with the code.

---

## Verify configuration paths

<!-- source: nrwl/nx | topic: Configurations | language: Markdown | updated: 2025-07-31 -->

Ensure configuration property paths are accurate and complete, especially for nested configurations and context-specific placement. Many configuration issues stem from incorrect or incomplete property paths that prevent features from working properly.

Key areas to verify:

1. **Nested property paths**: Use the full path for nested configurations
   - ✅ `release.docker.repositoryName` 
   - ❌ `release.repositoryName`

2. **Context-specific placement**: Ensure configurations are placed in the correct location based on project setup
   - For inferred targets: place sync generators inside the `nx` property in `package.json`
   - For Docker registries: configure at project level since it needs format like `myorg/app-name`

3. **Scope-appropriate configuration**: Match configuration scope to the intended behavior
   - Project-level configurations for project-specific settings
   - Workspace-level configurations for shared settings

Example of correct nested configuration:
```json
{
  "nx": {
    "release": {
      "docker": {
        "repositoryName": "myorg/my-app"
      }
    }
  }
}
```

Always double-check configuration paths against official documentation and test that configurations work as expected, as incorrect paths often fail silently or produce unexpected behavior.

---

## Environment variable validation

<!-- source: microsoft/playwright | topic: Configurations | language: TypeScript | updated: 2025-07-31 -->

Environment variables should be properly validated, parsed, and have sensible fallback values. Always validate boolean environment variables using explicit string comparisons rather than truthy checks, provide clear default values, and implement proper error handling for malformed values.

Key practices:
- Use explicit string comparisons for boolean environment variables: `process.env.VAR === '1' || process.env.VAR === 'true'`
- Provide meaningful defaults when environment variables are missing or invalid
- Support multiple formats when appropriate (e.g., `PLAYWRIGHT_FORCE_TTY` supporting boolean, width, or "widthxheight" formats)
- Use environment variables as feature gates for platform-specific or experimental functionality
- Validate and sanitize environment variable values before use

Example:
```typescript
// Good: Explicit validation with defaults
const headless = process.env.PLAYWRIGHT_HEADLESS === '1' || process.env.PLAYWRIGHT_HEADLESS === 'true';
const allowAndroid = process.env.PLAYWRIGHT_ALLOW_ANDROID === '1';

// Good: Complex parsing with fallbacks
const sizeMatch = process.env.PLAYWRIGHT_FORCE_TTY?.match(/^(\d+)x(\d+)$/);
if (sizeMatch) {
  ttyWidth = +sizeMatch[1];
  ttyHeight = +sizeMatch[2];
} else {
  ttyWidth = +process.env.PLAYWRIGHT_FORCE_TTY || DEFAULT_TTY_WIDTH;
}

// Bad: Truthy check without explicit validation
if (process.env.SOME_FLAG) { /* unreliable */ }
```

This prevents configuration bugs, improves security by requiring explicit opt-ins for sensitive features, and ensures consistent behavior across different environments.

---

## Use descriptive identifier names

<!-- source: microsoft/playwright | topic: Naming Conventions | language: TypeScript | updated: 2025-07-30 -->

Choose specific, descriptive names for variables, methods, types, and other identifiers that clearly communicate their purpose and behavior. Avoid generic names, unnecessary abbreviations, and assumptions about usage context.

**Key principles:**
- Method names should accurately reflect their behavior and scope (e.g., `_allNativeContexts` instead of `_allContexts` when the method only returns native contexts)
- Use descriptive type names instead of generic ones (e.g., `InstalledBrowserInfo` instead of `Options`)
- Avoid abbreviations in favor of clarity (e.g., `typedArrayConstructors` instead of `typedArrayCtors`)
- Choose unique, specific names to prevent conflicts (e.g., `alreadyRegistered` instead of `foo`)
- Don't assume specific use cases in naming (e.g., avoid `getAllByAria` if it's not exclusively for aria purposes)

**Example:**
```typescript
// Avoid generic or abbreviated names
type Options = { ... };  // ❌ Too generic
const typedArrayCtors = { ... };  // ❌ Unnecessary abbreviation

// Use descriptive, specific names
type InstalledBrowserInfo = { ... };  // ✅ Clear purpose
const typedArrayConstructors = { ... };  // ✅ Full, clear name

// Method names should reflect actual behavior
_allContexts() { return this._browserTypes().flatMap(...); }  // ❌ Misleading scope
_allNativeContexts() { return this._browserTypes().flatMap(...); }  // ✅ Accurate scope
```

This approach improves code readability, reduces confusion, and makes the codebase more maintainable by ensuring identifiers clearly communicate their intended purpose.

---

## Check operation failures

<!-- source: bazelbuild/bazel | topic: Error Handling | language: Other | updated: 2025-07-30 -->

Always validate inputs and check return values of operations that can fail, providing clear error messages when failures occur. This includes system calls, library functions, and user input validation.

For file operations, check return values and handle errors appropriately:
```cpp
FILE* procs = fopen(procs_path, "w");
if (procs != NULL) {
  if (fprintf(procs, "%d", pid) < 0) {
    // Log error and handle failure
  }
  if (fclose(procs) != 0) {
    // Log error and handle failure  
  }
}
```

For input validation, check for invalid states and provide helpful error messages:
```cpp
if (command.empty()) {
  blaze_util::StringPrintf(error, "Command cannot be the empty string (try 'help')");
  return nullptr;
}
```

Additionally, implement proactive measures to prevent predictable failures, such as proper argument escaping before passing to system commands. This defensive approach reduces the likelihood of runtime failures and makes debugging easier when issues do occur.

---

## validate input rigorously

<!-- source: microsoft/playwright | topic: Security | language: TypeScript | updated: 2025-07-30 -->

Always validate and sanitize input data against established standards to prevent injection attacks and ensure consistent behavior. This includes validating ARIA attributes according to W3C specifications and encoding potentially dangerous content in CSS or HTML contexts.

For ARIA attributes, ensure they follow W3C standards - aria-disabled should only apply to elements with suitable roles as defined in the specification. For CSS content, encode URLs that could break HTML parsing:

```typescript
// Validate ARIA attributes against standards
if (isAncestor || kAriaDisabledRoles.includes(getAriaRole(element) || '')) {
  // Only apply aria-disabled to elements with suitable roles
}

// Encode dangerous CSS URLs to prevent HTML injection
function escapeURLsInStyleSheet(text: string): string {
  const replacer = (match: string, url: string) => {
    // Conservatively encode only urls with a closing tag
    if (url.includes('</')) {
      return `url('${encodeURIComponent(url)}')`;
    }
    return match;
  };
  return text.replace(urlToEscapeRegex, replacer);
}
```

This prevents both accessibility bypasses and XSS attacks through malformed input that doesn't conform to expected standards.

---

## proxy configuration precedence

<!-- source: microsoft/playwright | topic: Networking | language: TypeScript | updated: 2025-07-29 -->

Ensure proxy configuration follows proper precedence hierarchy and handles different proxy types correctly. User-specified proxy settings should always take priority over environment variables, similar to how browsers handle proxy configuration.

When implementing proxy support:

1. **Prioritize user configuration over environment variables**:
```typescript
getProxyAgent(host: string, port: number) {
  const proxyFromEnv = getProxyForUrl(`https://${host}:${port}`);
  if (proxyFromEnv)
    return createProxyAgent({ server: proxyFromEnv });
  return createProxyAgent(this._proxy); // User config takes precedence
}
```

2. **Map proxy protocols correctly** - use `sslProxy` for HTTPS connections, not `httpsProxy`:
```typescript
switch (url.protocol) {
  case 'http:':
    proxy.httpProxy = url.host;
    break;
  case 'https:':
    proxy.sslProxy = url.host; // Not httpsProxy
    break;
}
```

3. **Handle legacy URL formats gracefully** while planning migration to modern URL objects:
```typescript
// TODO: switch to URL instance instead of legacy object once https-proxy-agent supports it.
return new HttpsProxyAgent(convertURLtoLegacyUrl(proxyOpts));
```

4. **Consider localhost proxy behavior** - some environments require explicit configuration to proxy localhost traffic, which should be handled appropriately for testing scenarios.

This approach ensures consistent proxy behavior across different network scenarios and maintains compatibility with existing proxy infrastructure while preparing for future modernization.

---

## reduce test verbosity

<!-- source: neovim/neovim | topic: Testing | language: Other | updated: 2025-07-28 -->

Write concise, efficient tests by eliminating repetitive code and combining related test cases. Avoid verbose patterns that can be simplified with better approaches.

Key strategies:
- Use multiline patterns instead of multiple `screen:expect()` calls with `unchanged=true`
- Write literal contents when known rather than using generic matchers like `{MATCH: +}`
- Combine related test cases into single tests when they save significant code (20+ lines)
- Create shared functions for tests that follow similar patterns
- Reuse existing test setup and assertions instead of creating new ones
- Keep validation tests concise - checking that a command requires an argument should only need ~2 lines

Example of verbose vs. concise screen testing:
```lua
-- Verbose (avoid):
screen:expect({ any = '.nvim.lua' })
screen:expect({ any = pesc('[i]gnore, (v)iew, (d)eny:'), unchanged = true })

-- Concise (prefer):
screen:expect({ any = 'Allowed.*\n.exrc' })
```

The goal is maintainable tests that clearly express intent without unnecessary repetition or complexity.

---

## Documentation accuracy standards

<!-- source: neovim/neovim | topic: Documentation | language: C | updated: 2025-07-28 -->

Ensure all function documentation accurately reflects the actual code behavior and includes complete, properly formatted descriptions of parameters and return values.

Key requirements:
1. **Match function signatures**: Documentation must accurately describe what the function actually does and returns. A void function should not claim to "return true".

2. **Complete parameter documentation**: All parameters must be documented with proper formatting:
   - Use `@param[in/out] name  Description` with two spaces after name
   - Align descriptions consistently
   - Avoid redundant phrases like "and description" when describing error parameters

3. **Proper return value documentation**: Use `@return` as the start of a sentence, not embedded within it:
   ```c
   // Incorrect:
   /// @return Always return 0.
   
   // Correct:
   /// @return always 0.
   ```

4. **Follow formatting conventions**: Use proper spacing, alignment, and structure as shown in established patterns:
   ```c
   /// Get information about Num/Caps/Scroll Lock state
   ///
   /// To be used in nvim_get_keyboard_mods_state() API function.
   ///
   /// @param[out]  dict  Pointer to dictionary where information about modifiers
   ///                    is to be dumped.
   /// @param[out]  err   Location where error message is to be saved, set to NULL
   ///                    if no error.
   ///
   /// @return true in case of error, false otherwise.
   ```

5. **Avoid unnecessary language**: Remove vague terms like "helper function" that don't add meaningful information to the documentation.

This ensures developers can rely on documentation to understand function behavior without needing to read the implementation.

---

## prioritize code readability

<!-- source: neovim/neovim | topic: Code Style | language: Other | updated: 2025-07-28 -->

Write code that prioritizes readability and clarity over brevity. Use proper formatting, clear expressions, and consistent patterns to make code easier to understand and maintain.

Key practices:
- Use string.format() for multiple concatenations instead of .. operators: `('Updated state to `%s` in `%s`'):format(version_str, name)` instead of `'Updated state to `' .. version_str .. '` in `' .. name .. '`'`
- Add parentheses to complex boolean expressions for clarity: `(metadata.conceal ~= nil) and metadata.conceal or (metadata[capture] and metadata[capture].conceal)` instead of `metadata.conceal ~= nil and metadata.conceal or metadata[capture] and metadata[capture].conceal`
- Put boolean variables directly in conditions rather than comparing to true/false: `if status then` instead of `if status == true then`
- Break complex declarations/assignments when they involve complex expressions: separate `local version_str = resolve_version()` and `local version_ref = get_reference()` instead of `local version_str, version_ref = resolve_version(), get_reference()`
- Use reasonable line length limits (120 characters) to avoid unnecessary line breaks that hurt readability
- Choose descriptive variable names and clear control flow patterns that make the code's intent obvious

The goal is to write code that another developer can quickly understand without having to parse complex expressions or guess at intentions.

---

## prefer concise expressions

<!-- source: neovim/neovim | topic: Code Style | language: C | updated: 2025-07-28 -->

Write concise, readable code by choosing the most direct expression for simple operations. Use ternary operators for simple boolean assignments instead of verbose if-else blocks, but avoid unnecessary ternaries when direct boolean assignment works. Return comparison results directly rather than using intermediate variables or verbose conditional blocks.

Examples of preferred concise expressions:

```c
// Good: Use ternary for simple assignment
hl.flags |= is_concealed ? kSHConceal : kSHConcealOff;

// Bad: Unnecessary ternary when direct boolean works
bool use_float = strstr(p_cot, "popup") != NULL ? true : false;
// Good: Direct boolean assignment
bool use_float = strstr(p_cot, "popup") != NULL;

// Good: Return comparison directly
return (GetKeyState(VK_CAPITAL) & 0x0001) != 0;

// Bad: Verbose conditional return
if ((GetKeyState(VK_CAPITAL) & 0x0001) != 0) {
  return 1;
} else {
  return 0;
}

// Good: Direct conditional check
if (!os_get_locks_status(&mods, err)) {
  return false;
}

// Bad: Unnecessary intermediate variable
bool status = os_get_locks_status(&mods, err);
if (!status) {
  return false;
}

// Good: Readable comparison order
wlv.char_attr = hl_combine_attr(wlv.vcol < TERM_ATTRS_MAX ? term_attrs[wlv.vcol] : 0, wlv.char_attr);
```

This approach reduces code verbosity while maintaining clarity, making the codebase more maintainable and easier to read.

---

## validate algorithmic edge cases

<!-- source: microsoft/playwright | topic: Algorithms | language: TypeScript | updated: 2025-07-28 -->

Algorithms must be thoroughly tested at boundary conditions and edge cases to prevent subtle bugs. Pay special attention to off-by-1 errors in mathematical calculations, empty collections, and boundary values that might cause unexpected behavior.

Common edge cases to validate:
- Mathematical boundaries (e.g., `Math.log10(10)` edge case)
- Empty or single-element collections
- Maximum/minimum values in ranges
- Conditional logic branches with complex state

Example from the codebase:
```javascript
// Problematic - fails for totalTestCount === 10
const indexLength = Math.ceil(Math.log10(this.totalTestCount));

// Correct - handles the edge case properly  
const indexLength = Math.ceil(Math.log10(this.totalTestCount + 1));
```

When implementing algorithms, create test cases that specifically target these boundary conditions. Consider reusing existing, well-tested algorithmic logic rather than reimplementing similar functionality, as proven algorithms are less likely to contain edge case bugs.

---

## follow protocol standards

<!-- source: neovim/neovim | topic: Networking | language: C | updated: 2025-07-28 -->

When implementing network protocols or communication formats, prioritize standardized specifications over legacy or device-specific formats, even when existing code uses older approaches. Legacy formats may work but can cause compatibility issues and confusion for applications that expect standard compliance.

For example, when implementing Device Attributes (DA) responses, use the standard format with proper parameter meanings rather than legacy device-specific formats:

```c
// Instead of legacy format that predates standardization:
char vterm_primary_device_attr[] = "1;2;52";  // Device-specific format

// Use standardized format:
char vterm_primary_device_attr[] = "61;52";   // Standard level-1 device with clipboard extension
```

Similarly, ensure protocol detection logic is explicit and follows expected patterns:

```c
// Clear boolean conversion for protocol detection
bool is_tcp = !!strrchr(server_address, ':');
```

This approach improves interoperability, reduces maintenance burden, and ensures your implementation works correctly with a broader range of clients and tools that expect standard-compliant behavior.

---

## Security warnings need guidance

<!-- source: neovim/neovim | topic: Security | language: Other | updated: 2025-07-28 -->

Security-related warnings and error messages should provide clear, actionable guidance on how users can safely resolve the issue, not just inform them of the problem. When displaying security warnings, include specific instructions that guide users through the secure workflow.

For example, instead of just stating a file is untrusted:
```lua
local msg = cwd .. pathsep .. 'Xfile is not trusted.'
```

Provide clear next steps:
```lua
local msg = cwd .. pathsep .. 'Xfile is not trusted. To enable it, choose (v)iew then run `:trust`.'
```

This approach helps users understand both the security concern and the proper way to address it, reducing the likelihood of unsafe workarounds or user confusion.

---

## consistent highlighting patterns

<!-- source: helix-editor/helix | topic: Code Style | language: Other | updated: 2025-07-27 -->

Maintain consistency in syntax highlighting patterns by using appropriate, specific scopes and avoiding overly complex or noisy patterns. Follow Helix-specific conventions rather than generic tree-sitter patterns.

Key guidelines:
- Use specific scopes like `@keyword.control.repeat` instead of generic `@keyword` when appropriate
- Use Helix-specific scopes like `@constant.numeric.integer` instead of generic `@number`
- Avoid overly complex patterns that try to guess highlighting context
- Remove noisy patterns like `(ERROR) @error` that distract during typing
- Use efficient patterns like `#any-of?` for multiple similar matches
- Ensure proper pattern precedence ordering (specific patterns before generic ones)
- Use cross-compatible predicates like `#match?` instead of platform-specific ones like `#lua-match?`

Example of good pattern specificity:
```scm
; Good - specific scopes
[
  "for"
  "while"
] @keyword.control.repeat

[
  "if" 
  "else"
] @keyword.control.conditional

; Avoid - overly generic
[
  "for"
  "while" 
  "if"
  "else"
] @keyword
```

Example of proper precedence:
```scm
; Specific pattern first
((comment) @comment.block.documentation
  (#match? @comment.block.documentation "^//!"))

; Generic pattern second  
(comment) @comment.line
```

This approach ensures highlighting is consistent, follows project conventions, and provides clear visual feedback without being distracting or overly complex.

---

## validate early, fail fast

<!-- source: neovim/neovim | topic: Error Handling | language: C | updated: 2025-07-27 -->

Perform comprehensive input validation and precondition checks at the beginning of functions, before executing any operations that could have side effects or modify system state. This prevents partial execution, inconsistent states, and resource leaks when validation fails.

Key principles:
- Validate all input parameters and their types before processing
- Check preconditions and system state before performing operations
- Handle all possible input combinations, not just the expected ones
- Fail immediately when validation fails, before any side effects occur

Example from the codebase:
```c
// BAD: Validation after side effects
FILE *f = fopen(path.data, "w");  // Side effect first
if (f == NULL) {
    return;  // But cursor was already moved
}

// GOOD: Validation before side effects  
if (HAS_KEY(opts, set_extmark, conceal)) {
    if (opts->conceal.type == kObjectTypeBoolean) {
        // Handle boolean case
    } else if (opts->conceal.type == kObjectTypeString) {
        // Handle string case  
    } else {
        // ERROR: type is neither string nor boolean
        goto error;
    }
}
```

This approach prevents crashes, data corruption, and difficult-to-debug partial state changes by catching problems before they can cause damage.

---

## API consistency patterns

<!-- source: neovim/neovim | topic: API | language: Other | updated: 2025-07-26 -->

Ensure similar API functions use consistent parameter patterns, types, and behaviors. When designing new APIs or modifying existing ones, identify related functions and align their interfaces to create predictable, reusable patterns.

Key principles:
- Use consistent parameter types across similar functions (e.g., if one diagnostic function accepts `namespace` as number|table, others should too)
- Reuse common utility types and builders rather than creating function-specific ones
- Maintain consistent capability announcements across related LSP features
- Apply the same parameter validation and handling patterns to similar functions

Example from diagnostic APIs:
```lua
-- Inconsistent: some functions support table namespace, others don't
vim.diagnostic.get(bufnr, { namespace = {ns1, ns2} })  -- supported
vim.diagnostic.open_float(opts)  -- namespace as table not supported

-- Consistent: all diagnostic functions handle namespace parameter the same way
vim.diagnostic.get(bufnr, { namespace = ns_or_table })
vim.diagnostic.open_float({ namespace = ns_or_table })
```

This approach reduces cognitive load for users, enables code reuse, and makes the API more maintainable. Before implementing new functionality, survey existing similar APIs and adopt their established patterns rather than inventing new ones.

---

## consistent naming conventions

<!-- source: neovim/neovim | topic: Naming Conventions | language: Other | updated: 2025-07-25 -->

Maintain consistent naming patterns and terminology across the codebase to reduce cognitive load and improve code clarity. The same concept should always use the same name in different contexts.

Key principles:
- Use established prefixes: `on_` for event handlers/callbacks, `is_` for boolean predicates, `get_` for accessors
- Follow codebase conventions: use `start`/`end` for ranges, `refresh()` for common update operations
- Avoid confusing similar terms: distinguish between "mode" and "modal", use descriptive names over generic ones
- Use consistent terminology across interfaces: if you call something "position" in one place, don't call it "location" elsewhere

Examples:
```lua
-- Good: consistent callback naming
function on_document_highlight(err, result, ctx) end

-- Bad: inconsistent suffix
function document_highlight_cb(err, result, ctx) end

-- Good: consistent terminology
local function get_logical_pos(diagnostic) end

-- Bad: mixing terminology  
local function get_logical_location(diagnostic) end

-- Good: established convention
local mark = { start_line = start_row, start_col = start_col }

-- Bad: non-standard naming
local mark = { begin_line = start_row, begin_col = start_col }
```

When introducing new names, check existing code for established patterns. Consistency trumps personal preference - if the codebase uses a particular naming convention, follow it even if you prefer alternatives.

---

## Complete function documentation

<!-- source: neovim/neovim | topic: Documentation | language: Other | updated: 2025-07-25 -->

Ensure all functions have comprehensive, accurate documentation including required tags (@param, @return, @since), clear descriptions that match actual behavior, and explanatory comments for complex logic.

Functions should include:
- All parameter descriptions with correct types
- Return value documentation that accurately describes what's returned
- Version tags (@since) for new features
- Brief explanatory comments for non-obvious code blocks

Example of complete documentation:
```lua
--- Makes an HTTP GET request to the given URL.
--- Can either return the body or save it to a file.
---
--- @param url string The URL to fetch.
--- @param opts? table Optional parameters:
---   - verbose (boolean|nil): Enables curl verbose output.
---   - retry   (integer|nil): Number of retries on transient failures (default: 3).
---   - output  (string|nil): If set, path to save response body instead of returning it.
--- @param on_exit? fun(err?: string, content?: string) Optional callback for async execution
--- @return string|boolean|nil Response body on success; `nil` on failure
--- @since 14
function M.get(url, opts, on_exit)
  -- Compute positions, set them as extmarks, and store in diagnostic._extmark_id
  -- (used by get_logical_location to adjust positions)
  once_buf_loaded(bufnr, function()
    -- complex logic here
  end)
end
```

Avoid confusing wording, inaccurate descriptions, or missing required documentation tags. Future developers should be able to understand the function's purpose, parameters, and behavior without studying the implementation.

---

## avoid error masking

<!-- source: neovim/neovim | topic: Error Handling | language: Other | updated: 2025-07-25 -->

Don't use mechanisms that suppress or hide errors unless absolutely necessary for the application flow. Error masking makes debugging difficult and can hide important issues from users and developers.

**Problematic patterns to avoid:**
- Using `pcall()` just to ignore errors: "pcall masks errors"
- Adding `silent!` to commands unnecessarily: "silent with '!' silences errors..."
- Using fragile error checking like `vim.v.shell_error`

**Better alternatives:**
- Use `vim.schedule()` if you need to prevent errors from disrupting flow
- Use proper error handling utilities like `t.pcall_err` for testing
- Use `vim.system():wait()` instead of `vim.fn.system()` to avoid fragile error handling
- Let errors propagate naturally unless you have a specific reason to handle them

**Example:**
```lua
-- Bad: Masks the actual error
local ok, _ = pcall(api.nvim_command, 'edit')

-- Better: Use proper error handling utility
eq(':edit command in prompt buffer throws error',
   t.pcall_err(api.nvim_command, 'edit'))

-- Bad: Silences all errors
nvim_command('silent! edit `=__fname`')

-- Better: Let errors show unless specifically needed
nvim_command('edit `=__fname`')
```

Only suppress errors when you have a clear reason and a plan for handling the error condition appropriately.

---

## avoid unnecessary configuration

<!-- source: neovim/neovim | topic: Configurations | language: Txt | updated: 2025-07-25 -->

Avoid creating special-purpose configuration options when simpler alternatives exist. Don't force users to call setup functions or provide explicit configuration for basic functionality to work.

As noted in the discussions: "special-purpose options are clumsy and a maintenance burden" and "users will be forced to call this function in order to use your plugin, even if they are happy with the default configuration."

Instead of creating configuration options, consider:
- Documenting event handlers that users can copy into their config
- Allowing plugins to work out of the box with smart defaults
- Separating configuration from initialization logic
- Using existing Vim mechanisms like autocommands or filetype detection

Example of what to avoid:
```lua
-- Don't force this pattern
vim.g.query_autoreload_on = { 'InsertLeave', 'TextChanged' }

-- Instead, document the underlying mechanism
vim.api.nvim_create_autocmd('BufWritePost', {
  pattern = '*.scm',
  callback = function() vim.treesitter.query.invalidate_cache() end
})
```

For operations that require user consent (like network downloads), provide confirmation prompts rather than configuration flags. This maintains security while avoiding configuration complexity.

---

## consolidate network APIs

<!-- source: neovim/neovim | topic: Networking | language: Other | updated: 2025-07-24 -->

When implementing network functionality, consolidate around standardized APIs like `vim.net.request()` instead of maintaining custom download functions or direct curl calls. Implement comprehensive testing for network operations using integration test guards to prevent failures in environments without network access.

Key practices:
- Replace custom download/HTTP functions with `vim.net.request()`
- Guard network-dependent tests with environment variables (e.g., `NVIM_TEST_INTEG`)
- Test both text and binary response handling
- Use `t.skip()` to conditionally skip network tests when integration testing is disabled

Example implementation:
```lua
-- Instead of custom download functions
local function download(url)
  -- Replace with vim.net.request()
end

-- Proper test guarding
describe('network functionality', function()
  local skip_integ = os.getenv('NVIM_TEST_INTEG') ~= '1'
  
  it('handles text responses', function()
    if skip_integ then t.skip() end
    -- network test implementation
  end)
  
  it('handles binary responses', function()
    if skip_integ then t.skip() end
    -- binary response test
  end)
end)
```

This approach ensures consistent network handling across the codebase while maintaining testability in various environments.

---

## Use semantically accurate names

<!-- source: electron/electron | topic: Naming Conventions | language: Markdown | updated: 2025-07-24 -->

Choose parameter and method names that accurately reflect their semantic meaning and implementation reality, rather than names that may be misleading or platform-specific.

Avoid names that imply specific technical requirements when the actual implementation is more flexible. For example, a parameter named `guid` suggests it must be a GUID format, when the implementation may accept any unique string identifier.

Similarly, method names should accurately describe their action. Names like `evaluate` can be misleading if they suggest using `eval()` when the actual implementation executes code differently.

Examples of improvements:
- `guid` → `identifier` (when the parameter accepts any unique string, not just GUIDs)
- `roundedCorner` → `roundedCorners` (when the property affects multiple corners)
- `evaluateInMainWorld` → `executeScriptInMainWorld` (when the method executes rather than evaluates code)

This principle helps prevent developer confusion and makes APIs more intuitive across different platforms and use cases.

---

## avoid redundant CI operations

<!-- source: nrwl/nx | topic: CI/CD | language: TypeScript | updated: 2025-07-24 -->

CI/CD processes should eliminate unnecessary repetition and redundant operations across projects and builds. This includes avoiding repeated warning messages, preferring template-based configurations over runtime string replacements, and ensuring operations are performed once at the appropriate level rather than repeatedly for each project.

Key practices:
- Show warnings once during the overall process (e.g., nx-release) rather than once per project
- Use template files for configuration instead of runtime string manipulation
- Structure build dependencies properly to avoid redundant transpilation steps

Example of the problem:
```typescript
// Avoid: Warning shown for every project
logger.warn(
  `Docker support is experimental. Breaking changes may occur and not adhere to semver versioning.`
);

// Better: Show warning once at the process level during nx-release
```

Example of preferred approach:
```typescript
// Instead of runtime string replacement logic
// Update the template at packages/node/src/generators/application/files/common/webpack.config.js__tmpl__
// This ensures consistent configuration without repeated processing
```

This approach reduces build times, minimizes log noise, and creates more maintainable CI/CD pipelines by eliminating unnecessary duplication of operations.

---

## API parameter consistency

<!-- source: electron/electron | topic: API | language: Other | updated: 2025-07-23 -->

Ensure consistent parameter handling across API methods by using appropriate defaults, proper type conversion, validation with meaningful constants, and cross-platform behavior consistency.

Key practices:
- **Use default parameters** to simplify common use cases: `void SetBounds(const gfx::Rect& bounds, bool animate = false)`
- **Leverage built-in type converters** instead of manual string conversion: `dict.Get("frameOrigin", &frame_origin_url)` where `frame_origin_url` is a `GURL`
- **Use symbolic constants with documentation** for validation: `constexpr int kMinSizeReqdBySpec = 100; // Per Web API spec`
- **Apply consistent validation patterns**: `width = std::max(kMinSizeReqdBySpec, inner_width)`
- **Provide consistent fallback values**: Use "unknown" instead of empty strings for enum-like values
- **Use std::move() for optional parameters**: `SetUserAgent(user_agent, std::move(ua_metadata))`
- **Maintain cross-platform consistency**: Either implement identical behavior across platforms or explicitly gate platform-specific APIs
- **Avoid hardcoded values**: Make configurable what users might want to customize (e.g., animation duration)

This approach reduces API complexity, improves type safety, and ensures predictable behavior across different platforms and use cases.

---

## Maintain clean code structure

<!-- source: hyprwm/Hyprland | topic: Code Style | language: Other | updated: 2025-07-23 -->

Keep code well-organized by separating interface from implementation, managing dependencies properly, and following consistent structural patterns. Function bodies should remain in implementation files rather than headers to reduce compilation dependencies and improve maintainability. Organize includes strategically - move them to implementation files when possible and always use relative paths rather than src-based paths. Structure classes and functions appropriately by preferring namespaces over global functions, placing functions within relevant classes when they operate on class data, and following standard member ordering with private members last. Avoid unnecessary code elements like redundant `this` usage.

Example of proper structure:
```cpp
// Header file - interface only
class CHyprCtl {
public:
    static std::string getWindowData(PHLWINDOW w, eHyprCtlOutputFormat format);
private:
    // private members come last
    wl_event_source* m_eventSource = nullptr;
};

// Implementation file - bodies and includes
#include "relative/path/to/header.hpp"  // relative paths only
#include <fcntl.h>  // moved from global includes

std::string CHyprCtl::getWindowData(PHLWINDOW w, eHyprCtlOutputFormat format) {
    // implementation here, avoid unnecessary 'this->'
    return result;
}
```

---

## comprehensive edge case testing

<!-- source: bazelbuild/bazel | topic: Testing | language: Other | updated: 2025-07-23 -->

Write comprehensive tests that cover edge cases and platform-specific scenarios to uncover underlying implementation issues rather than masking them with workarounds. When encountering failures, investigate the root cause through targeted testing before implementing fallback mechanisms.

For platform-specific issues, add integration tests that run on the affected platforms:
```cpp
// Instead of adding fallbacks like:
if (!IsReadableFile(*result)) {
  // fallback logic
}

// Add platform-specific integration tests to investigate the root cause
```

For complex functionality, test edge cases systematically:
```java
// Test comprehensive scenarios like:
// * UTF-16 strings with non-ASCII BMP characters
// * UTF-16 strings with surrogate pairs  
// * Latin1-hack strings with invalid UTF-8
// * Unpaired surrogates in various positions
```

This approach often reveals bugs in existing implementations that would otherwise remain hidden. As noted in one review: "This was both a nightmare and super helpful as the previous implementation had a number of bugs." Comprehensive testing serves as both quality assurance and debugging tool, helping teams understand the true behavior of their code rather than working around symptoms.

---

## avoid runtime credential resolution

<!-- source: electron/electron | topic: Security | language: Shell | updated: 2025-07-23 -->

Security credentials and access control mechanisms should be pre-configured at deployment or configuration time rather than resolved dynamically at runtime. Dynamic credential fetching introduces injection risks and makes security boundaries harder to audit and control.

Instead of fetching credentials from APIs or using runtime variables for security decisions, embed credentials in secure configuration stores (like Terraform-managed secrets) or integrate with centralized identity providers and zero-trust systems.

Example of problematic runtime resolution:
```bash
# Risky: Dynamic API call with potentially injectable variable
api_response=$(curl -s "https://api.github.com/users/$GITHUB_ACTOR/keys")
echo "$api_response" | jq -r '.[].key' > authorized_keys
```

Preferred approaches:
```bash
# Better: Pre-configured credentials from secure store
echo "$PRECONFIGURED_SSH_KEYS" > authorized_keys

# Best: Centralized identity-based access control
# Configure hostname as SSH target in zero-trust system
# Assign IDP roles (e.g., wg-infra) access to hostname
```

This approach eliminates injection vectors, improves auditability, and centralizes security policy management.

---

## Scope configuration impact

<!-- source: electron/electron | topic: Configurations | language: Yaml | updated: 2025-07-23 -->

{% raw %}
When implementing configuration settings, carefully consider and limit their scope to prevent unintended broad impact across systems or workflows. Configuration changes should be targeted and controlled rather than applied globally when only specific contexts require them.

For example, instead of enabling debugging for all pipelines:
```yaml
env:
  ACTIONS_STEP_DEBUG: ${{ secrets.ACTIONS_STEP_DEBUG }}
```

Consider using conditional logic to scope the configuration:
```yaml
env:
  ACTIONS_STEP_DEBUG: ${{ github.ref == secrets.DEBUG_BRANCH_NAME && secrets.ACTIONS_STEP_DEBUG || '' }}
```

Similarly, when processing configuration-driven logic, implement safeguards to prevent excessive or uncontrolled behavior:
```javascript
// Add limits to prevent configuration from causing excessive operations
labels.push(versionLabel);
if (labels.length >= 5) {
  break;
}
```

This approach ensures configuration changes remain predictable and don't inadvertently affect unrelated parts of the system.
{% endraw %}

---

## manage object lifetimes carefully

<!-- source: microsoft/terminal | topic: Concurrency | language: C++ | updated: 2025-07-22 -->

Ensure proper object lifetime management in concurrent scenarios to prevent crashes from dangling pointers and premature destruction. Use weak references for event handlers that may outlive their target objects, and capture strong references in async operations to keep objects alive during coroutine execution.

Key practices:
- Use `get_weak()` pattern for event handlers: `handler({ get_weak(), &Class::Method })` instead of raw `this` pointers
- Avoid leaving dangling event handlers with raw pointers when objects can be destroyed while events are still registered
- In coroutines, capture strong references to `this` when the object needs to stay alive across async boundaries: `auto strongThis = get_self<implementation::ClassName>();`
- Be cautious about background thread destruction - objects destroyed on background threads can break UI frameworks like WinUI

Example of proper weak reference usage:
```cpp
// Good: Uses weak reference pattern
_connection.StateChanged(winrt::auto_revoke, { get_weak(), &ControlCore::_connectionStateChangedHandler });

// Bad: Raw pointer that can dangle
_accessibilitySettings.HighContrastChanged([this](auto&&, auto&&) { 
    // 'this' may be destroyed while handler is still registered
});
```

This prevents race conditions where objects are destroyed while concurrent operations are still referencing them, which is a common source of crashes in multithreaded applications.

---

## consistent nullable returns

<!-- source: electron/electron | topic: Null Handling | language: Markdown | updated: 2025-07-22 -->

Establish consistent patterns for nullable return values in APIs and document them clearly. Use `null` consistently for "not found" or "unavailable" cases rather than mixing `null`, `undefined`, and `false`. Always document when and why nullable values are returned, explaining the specific conditions that lead to these values.

For return type documentation, specify the nullable type and provide clear explanations:

```typescript
// Good: Consistent use of null with clear documentation
Returns `WebContents | null` - The `WebContents` owned by this view 
or `null` if the contents are destroyed.

Returns `WebFrameMain | null` - A frame with the given process and frame token,
or `null` if there is no WebFrameMain associated with the given IDs.

// Avoid: Mixing null, undefined, and false inconsistently
Returns `string | false` // when documented as `string | null`
Returns `ServiceWorkerMain | undefined` // when other APIs use `null`
```

Ensure implementation matches documentation - if the docs specify `string | null`, the implementation should return `null`, not `false` or `undefined`. This consistency helps developers understand and handle edge cases predictably across the entire API surface.

---

## Optimize algorithmic complexity

<!-- source: neovim/neovim | topic: Algorithms | language: Other | updated: 2025-07-22 -->

Actively identify and eliminate unnecessary computational overhead in algorithms, particularly focusing on nested loops and inefficient data operations that can significantly impact performance.

Key areas to review:

1. **Nested Loop Analysis**: Question the necessity of multiple nested loops. As seen in diagnostic processing code, triple-nested loops were "completely unnecessary" and could be eliminated entirely. Always ask: "Can this nesting be reduced or avoided?"

2. **String Building Efficiency**: Avoid repeated string concatenation in loops, which creates O(n²) complexity. Instead, use table-based accumulation:

```lua
-- Inefficient: O(n²) due to string immutability
local result = ''
for char in text do
  result = result .. char  -- Creates new string each time
end

-- Efficient: O(n) using table accumulation
local parts = {}
for char in text do
  table.insert(parts, char)
end
local result = table.concat(parts)
```

3. **Iterator Overhead**: When implementing custom iterators, avoid expensive operations like pack/unpack for multiple return values. Consider the performance implications of each abstraction layer and whether the convenience justifies the overhead.

4. **Algorithmic Alternatives**: Before implementing complex nested logic, research if existing utilities or algorithms can solve the problem more efficiently. For example, reusing proven range-checking logic instead of reimplementing it.

The goal is to maintain code clarity while ensuring algorithms scale appropriately with input size. When in doubt, prefer simpler algorithms with better complexity characteristics over complex optimizations that may introduce bugs.

---

## Comprehensive JSDoc with examples

<!-- source: microsoft/vscode | topic: Documentation | language: TypeScript | updated: 2025-07-22 -->

Write thorough JSDoc comments for interfaces, functions, and methods that clearly explain their purpose and behavior. Include:

1. A main description explaining the component's purpose
2. Documentation for all parameters and properties, especially highlighting differences between similarly named items
3. Concrete examples for complex logic to illustrate different use cases

For interfaces:
```typescript
/**
 * Represents a configured task in the system.
 * 
 * This interface is used to define tasks that can be executed within the workspace.
 * It includes optional properties for identifying and describing the task.
 * 
 * Properties:
 * - `type`: (optional) The type of the task, which categorizes it (e.g., "build", "test").
 * - `label`: (optional) A user-facing label for the task, typically used for display purposes.
 * - `_label`: (optional) An internal label for the task, used for unique identification.
 */
interface IConfiguredTask {
    type?: string;
    label?: string;
    _label?: string;
}
```

For functions:
```typescript
/**
 * Determines the type of token based on command line and cursor position.
 * 
 * Examples:
 * - `getTokenType({commandLine: "git commit", cursorPosition: 3}, TerminalShellType.Bash)`
 *   Returns TokenType.Command as cursor is within the command
 * - `getTokenType({commandLine: "git commit -m", cursorPosition: 11}, TerminalShellType.Bash)`
 *   Returns TokenType.Argument as cursor is after a command argument flag
 * 
 * @param ctx The command context containing command line and cursor position
 * @param shellType The type of shell being used
 * @returns The determined token type based on context
 */
function getTokenType(ctx: { commandLine: string; cursorPosition: number }, shellType: TerminalShellType | undefined): TokenType {
    // Implementation
}
```

Prefer descriptive main comments over tag-only documentation and ensure every component of your API is properly documented. This practice significantly improves code maintainability and reduces onboarding time for new developers.

---

## Eliminate unnecessary code patterns

<!-- source: microsoft/vscode | topic: Code Style | language: TypeScript | updated: 2025-07-21 -->

Remove redundant code patterns that add complexity without value. This includes:

1. Duplicate code blocks - Extract shared logic into reusable functions
2. Redundant conditions - Avoid rechecking conditions that were already verified
3. Unnecessary control flow - Remove else blocks when if blocks return
4. Repeated inline code - Create helper functions for common patterns

Example of simplifying control flow:

```typescript
// Before
if (filename.endsWith(PROMPT_FILE_EXTENSION)) {
    return filename.slice(0, -PROMPT_FILE_EXTENSION.length);
} else if (filename.endsWith(INSTRUCTION_FILE_EXTENSION)) {
    return filename.slice(0, -INSTRUCTION_FILE_EXTENSION.length);
} else if (filename === COPILOT_CUSTOM_INSTRUCTIONS_FILENAME) {
    return filename.slice(0, -3);
}

// After
if (filename.endsWith(PROMPT_FILE_EXTENSION)) {
    return filename.slice(0, -PROMPT_FILE_EXTENSION.length);
}

if (filename.endsWith(INSTRUCTION_FILE_EXTENSION)) {
    return filename.slice(0, -INSTRUCTION_FILE_EXTENSION.length);
}

if (filename === COPILOT_CUSTOM_INSTRUCTIONS_FILENAME) {
    return filename.slice(0, -3);
}
```

For repeated patterns, extract into helper functions:

```typescript
// Before
const FAILED_TASK_STATUS = { icon: { ...Codicon.error, color: { id: problemsErrorIconForeground } }};
const WARNING_TASK_STATUS = { icon: { ...Codicon.warning, color: { id: problemsWarningIconForeground } }};

// After
const createColoredIcon = (icon: Codicon, colorId: string) => ({ ...icon, color: { id: colorId }});
const FAILED_TASK_STATUS = { icon: createColoredIcon(Codicon.error, problemsErrorIconForeground) };
const WARNING_TASK_STATUS = { icon: createColoredIcon(Codicon.warning, problemsWarningIconForeground) };
```

---

## Write specific test assertions

<!-- source: bazelbuild/bazel | topic: Testing | language: Shell | updated: 2025-07-21 -->

Make test assertions specific and verifiable rather than relying on generic metrics or counts. Use explicit checks for expected behaviors and implement proper error handling to ensure tests fail fast when something goes wrong.

Instead of asserting on generic counts like "2 total actions", verify that specific actions were executed by using detailed logging and targeted assertions:

```bash
# Poor: Generic assertion
expect_log "2 total actions"

# Better: Specific assertion  
bazel build --experimental_ui_debug_all_events //pkg:a
expect_log "Executing genrule //pkg:a"
```

Additionally, use proper error handling mechanisms like `set -e` in shell tests to ensure failures are caught immediately:

```bash
#!/bin/sh
set -e  # Fail fast on any error
touch "$TEST_TMPDIR/test_file"  # Will properly fail if directory not writable
```

This approach makes tests more reliable, easier to debug when they fail, and provides clearer feedback about what specifically went wrong during test execution.

---

## Add explanatory comments

<!-- source: bazelbuild/bazel | topic: Documentation | language: Java | updated: 2025-07-20 -->

Add explanatory comments and documentation for complex logic, non-obvious code behavior, method parameters, and API functionality to improve code readability and maintainability.

This applies to several scenarios:
- Complex algorithms or logic that aren't immediately clear from the code
- Boolean parameters or magic values that need explanation
- Method behavior that has side effects or special conditions
- Constructor parameters and their roles
- API methods missing complete documentation

Examples:
```java
// Comment explaining complex logic
if (entry.getKey() == null) {
  // Remove entry when key is null - using value as the key to remove
  normalizedEntries.remove(entry.getValue());
}

// Comment explaining boolean parameter meaning
SpawnInputExpander spawnInputExpander = new SpawnInputExpander(execRoot, /* relativeToExecRoot= */ false);

// Complete method documentation
/**
 * Renames the file or directory from src to dst.
 * Parent directories are created as needed. If the target already exists, it will be overwritten.
 * 
 * @param clientEnv the client environment variables used for subprocess execution
 */
```

The goal is to make code self-documenting through clear comments that explain the "why" behind non-obvious implementation decisions, parameter meanings, and expected behavior.

---

## avoid expensive hot paths

<!-- source: hyprwm/Hyprland | topic: Performance Optimization | language: C++ | updated: 2025-07-20 -->

Identify and optimize expensive operations in frequently executed code paths to prevent performance bottlenecks. Hot paths include rendering loops, input event handlers, and frequently called utility functions.

Key optimization strategies:
1. **Cache expensive results**: Store results of expensive operations (system calls, config lookups, X server queries) and reuse them instead of recalculating
2. **Early bailout conditions**: Add early return statements to skip unnecessary work when conditions aren't met
3. **Move expensive operations out of loops**: Relocate costly operations like config lookups to initialization or setup phases

Example of caching expensive system calls:
```cpp
static bool checkDrmSyncobjTimelineSupport(int drmFD) {
    static bool cached = false;
    static bool result = false;
    if (!cached) {
        uint64_t cap = 0;
        int ret = drmGetCap(drmFD, DRM_CAP_SYNCOBJ_TIMELINE, &cap);
        result = (ret == 0 && cap != 0);
        cached = true;
    }
    return result;
}
```

Example of early bailout optimization:
```cpp
void damageEntireParent() {
    CBox box = getParentBox();
    if (box.empty())  // Skip expensive damage calculation
        return;
    g_pHyprRenderer->damageBox(box);
}
```

Avoid config lookups in hot paths like input handlers - instead store values in object state during initialization. This prevents "extreme performance kill" scenarios where expensive operations execute on every mouse movement or render frame.

---

## preserve URL integrity

<!-- source: mountain-loop/yaak | topic: API | language: TypeScript | updated: 2025-07-19 -->

When manipulating URLs for API calls, prioritize preserving the original URL structure over using convenience APIs that may normalize or modify the URL unexpectedly. This is especially important when appending query parameters or handling URL fragments.

Use manual string building approaches when you need to maintain exact URL formatting, as browser APIs like `new URL()` may normalize paths, convert case, or modify other URL components in ways that could break existing API integrations.

Example approach for parameter appending:
```typescript
// Avoid: May normalize the URL
const urlObj = new URL(finalUrl);
urlParams.forEach(p => urlObj.searchParams.append(p.name, p.value));

// Prefer: Preserves original URL structure
const [base, hash] = finalUrl.split('#');
const separator = base.includes('?') ? '&' : '?';
const queryString = urlParams
  .map(p => `${encodeURIComponent(p.name)}=${encodeURIComponent(p.value)}`)
  .join('&');
finalUrl = base + separator + queryString + (hash ? `#${hash}` : '');
```

Always test URL manipulation with edge cases including fragments, special characters, and non-standard but valid URL formats to ensure your API calls work with diverse endpoint structures.

---

## Validate nullability with types

<!-- source: microsoft/vscode | topic: Null Handling | language: TypeScript | updated: 2025-07-18 -->

Always handle null and undefined values explicitly through proper type declarations and validation patterns rather than using non-null assertions or unsafe type casts. This ensures type safety and prevents runtime errors.

Key practices:
1. Use type declarations to make nullability explicit
2. Implement proper validation before accessing potentially null values
3. Prefer assignment patterns over non-null assertions
4. Use type-safe alternatives like optional chaining and nullish coalescing

Example:

```typescript
// ❌ Avoid
function processItem(item: Item | undefined) {
    return item!.value; // Unsafe non-null assertion
}

// ✅ Better
function processItem(item: Item | undefined) {
    if (!item) {
        return undefined;
    }
    return item.value;
}

// ✅ Even better - using type guards
function processItem(item: Item | undefined): string | undefined {
    if (isValidItem(item)) {
        return item.value;
    }
    return undefined;
}

// ✅ Best - with proper typing and validation
interface ItemProcessor {
    process(item: Item): string;
}

class SafeItemProcessor implements ItemProcessor {
    process(item: Item): string {
        // Type system ensures item is never null/undefined
        return item.value;
    }
}
```

---

## Parallelize independent operations

<!-- source: microsoft/vscode | topic: Concurrency | language: TypeScript | updated: 2025-07-18 -->

When writing concurrent code, always execute independent operations in parallel rather than sequentially to improve performance and responsiveness. Using parallel execution patterns can significantly reduce waiting time for I/O-bound operations.

For API calls or file operations that don't depend on each other:

```typescript
// Instead of sequential execution:
const entitlements = await this.getEntitlements(session.accessToken, tokenEntitlementUrl);
const chatEntitlements = await this.getChatEntitlements(session.accessToken, chatEntitlementUrl);

// Prefer parallel execution:
const [entitlements, chatEntitlements] = await Promise.all([
  this.getEntitlements(session.accessToken, tokenEntitlementUrl),
  this.getChatEntitlements(session.accessToken, chatEntitlementUrl)
]);
```

When implementing operations that can take variable time to complete:
1. Consider using `Promise.race()` to process results as they arrive
2. Always respect cancellation tokens in long-running operations
3. Include proper cleanup mechanisms after parallel execution

Remember that excessive parallelism can lead to resource contention, so balance parallelism with the available system resources. For CPU-bound tasks, consider using worker threads or a task queue to prevent blocking the main thread.

---

## Ensure documentation completeness

<!-- source: bazelbuild/bazel | topic: Documentation | language: Other | updated: 2025-07-17 -->

All code elements should have sufficient documentation to understand their purpose, usage, and context. This includes adding explanatory comments for non-obvious constants, documenting private functions for maintainability, ensuring grammatical accuracy in all documentation, and providing necessary context such as prerequisites or limitations.

Key areas to address:
- Add comments to constants or variables that aren't self-explanatory (e.g., `DWP = "dwp"  // Name of the debug package action`)
- Document private functions with dev-facing comments explaining their purpose
- Review documentation for grammatical accuracy and clarity
- Include relevant context like version requirements, prerequisites, or usage limitations

Example of complete documentation:
```cpp
// Returns the repository name for the current source file.
// Requires C++20 support for __builtin_FILE functionality.
// Use this from within `cc_test` rules.
static std::string CurrentRepository(const std::string& file = __builtin_FILE());
```

This ensures that future developers can understand and maintain the code without needing to reverse-engineer functionality or guess at requirements.

---

## Use explicit identifiers

<!-- source: nrwl/nx | topic: Naming Conventions | language: Rust | updated: 2025-07-17 -->

Choose explicit, unambiguous names for functions, variables, and parameters to avoid conflicts with common types and reduce reliance on implicit assumptions. Prefer descriptive names that clearly indicate purpose over generic terms that might be confused with built-in types or require string parsing.

For function names, avoid generic terms like `error` that commonly appear as type instances. Instead, use prefixed names like `log_error` or `logError` to clearly indicate the function's purpose.

For parameters, prefer explicit values over implicit extraction. Rather than parsing identifiers from formatted strings, pass the required values directly as separate parameters.

Example:
```rust
// Avoid: Generic name that conflicts with Error type
pub fn error(message: String) { ... }

// Prefer: Explicit, descriptive name
pub fn log_error(message: String) { ... }

// Avoid: Implicit extraction from formatted strings
let project_name = task_id.split(':').next().unwrap_or(task_id);

// Prefer: Explicit parameter passing
fn process_task(task_id: String, project_name: String) { ... }
```

---

## Descriptive semantic naming

<!-- source: microsoft/vscode | topic: Naming Conventions | language: Json | updated: 2025-07-17 -->

Names should accurately reflect their purpose and behavior, providing users and developers with clear expectations. For identifiers, use specific qualifiers that indicate their intended context rather than generic terms. For UI elements like commands, ensure the name accurately represents the behavior (e.g., only use ellipsis '...' when additional input will be requested).

Good example:
```json
{
  "id": "chat-instructions",  // Qualified to show specific purpose
  "command": "Delete Worktree"  // No ellipsis as no picker is shown
}
```

Poor example:
```json
{
  "id": "instructions",  // Too generic, lacks context
  "command": "Delete Worktree..."  // Misleading ellipsis suggests a picker
}
```

---

## Update security patches regularly

<!-- source: microsoft/vscode | topic: Security | language: Other | updated: 2025-07-17 -->

Always keep dependencies, runtime environments, and libraries updated with the latest security patches to mitigate known vulnerabilities. Prioritize security updates even for minor version changes.

Example:
```
# Incorrect
# .nvmrc
22.15.1

# Correct
# .nvmrc
22.17.1  # Latest version with security fixes
```

Regular dependency updates are a critical security practice. When security patches are available (like Node.js 22.17.1 that fixes security issues), they should be applied promptly rather than waiting for future update cycles. Establish a process for monitoring security advisories related to your project dependencies and implement patches in a timely manner.

---

## optimize algorithmic efficiency

<!-- source: electron/electron | topic: Algorithms | language: Other | updated: 2025-07-16 -->

Choose efficient data structures and algorithms to minimize computational overhead and improve performance. This involves selecting appropriate containers based on usage patterns, avoiding unnecessary operations like redundant copies or conversions, and leveraging optimized library functions.

Key practices:
- Use performance-optimized containers like `absl::flat_hash_map` instead of `std::unordered_map`, or `base::MakeFixedFlatSet` for compile-time known sets
- Avoid redundant type conversions or parsing by consolidating logic in a single location
- Eliminate unnecessary copies in loops by using references (`const auto& item`) or range-based algorithms
- Prefer standard library algorithms like `base::ranges::any_of` over custom implementations
- Use direct object comparisons instead of converting to intermediate representations when possible
- Avoid unnecessary `std::move` on temporary values that already have move semantics

Example of optimization:
```cpp
// Less efficient - custom loop with copies
for (size_t i = 0; i < val.planes.size(); ++i) {
  auto plane = val.planes[i];  // Unnecessary copy
  // process plane...
}

// More efficient - range-based with references
for (const auto& plane : val.planes) {
  // process plane...
}

// Even better - use library algorithms when applicable
auto v8_planes = base::ToVector(val.planes, [isolate](const auto& plane) {
  // transform logic...
});
```

This approach reduces computational complexity, memory usage, and improves overall performance by making algorithmic choices that align with actual usage patterns.

---

## avoid redundant operations

<!-- source: electron/electron | topic: Performance Optimization | language: Other | updated: 2025-07-16 -->

Identify and eliminate unnecessary duplicate operations, redundant function calls, and repeated computations that can impact performance. Common patterns include: avoiding redundant parameter retrieval when values are already available, preventing duplicate map lookups by caching results, checking for changes before performing expensive operations, and caching expensive computations for reuse.

Examples of optimization opportunities:
- Pass available parameters instead of recalculating: `UpdateWindowAccentColor(active)` rather than calling `IsActive()` again
- Cache map lookup results: `if (const auto* orig = base::FindOrNull(options.environment, key))` instead of separate `find()` and second lookup
- Guard expensive operations with change detection: `if (title == GetTitle()) return;` before triggering update events
- Cache expensive computations in static storage: `base::NoDestructor<std::string>` for values computed repeatedly during module loading
- Reuse V8 string objects: Create `v8::Local<v8::String>` keys once and reuse them instead of recreating identical strings multiple times

Consider debouncing rapidly-triggered operations like window state saves during resize events to prevent performance degradation from excessive I/O operations.

---

## Reuse defined resources consistently

<!-- source: microsoft/terminal | topic: Code Style | language: Other | updated: 2025-07-16 -->

Always reuse existing defined constants, resources, and reusable components instead of duplicating values or creating redundant implementations. This improves maintainability, ensures consistency across the codebase, and reduces the risk of introducing inconsistencies when values need to be updated.

Key practices:
- Reference existing resource definitions like `{StaticResource StandardControlMaxWidth}` instead of hardcoding values like "1000"
- Consolidate duplicate styles that serve the same purpose (e.g., merge `SettingsStackStyle` and `PivotStackStyle` if they're identical)
- Move reusable utility functions to shared locations like converters for project-wide access
- Avoid introducing duplicate constants across compilation units by moving them into appropriate scopes

Example of good practice:
```xml
<!-- Good: Reuse existing resource -->
<muxc:BreadcrumbBar MaxWidth="{StaticResource StandardControlMaxWidth}" />

<!-- Bad: Hardcode the same value -->
<muxc:BreadcrumbBar MaxWidth="1000" />
```

Example for C++ constants:
```cpp
// Good: Move constant into function scope to avoid duplication
uint64_t rapidhash_withSeed(const void* key, size_t len, uint64_t seed) {
    static const uint64_t rapid_secret[3] = { /* values */ };
    // use rapid_secret here
}

// Bad: Global constant duplicated in every compilation unit
static const uint64_t rapid_secret[3] = { /* values */ };
```

This approach reduces maintenance burden and ensures consistent behavior across the application.

---

## Avoid unnecessary computations

<!-- source: bazelbuild/bazel | topic: Performance Optimization | language: Java | updated: 2025-07-15 -->

Before performing expensive operations, check if the work is actually needed or if more efficient alternatives exist. This includes validating preconditions, using optimized system calls, and avoiding duplicate method invocations.

Key patterns to apply:

1. **Guard expensive operations with feature flags**: Don't perform costly work when features are disabled. For example, avoid expensive cache pruning operations that add startup time for users not using the feature.

2. **Use efficient system calls**: Replace multiple system calls with single, more informative ones:
```java
// Instead of:
if (!path.exists()) {
  return true;
}

// Use:
var stat = path.statNullable();
if (stat == null) {
  return true;
}
```

3. **Cache method results**: Avoid calling the same method multiple times:
```java
// Instead of:
if(Profiler.getProcessCpuTimeMaybe() != null) {
  // ... use Profiler.getProcessCpuTimeMaybe() again
}

// Use:
var processCpuTime = Profiler.getProcessCpuTimeMaybe();
if(processCpuTime != null) {
  // ... use processCpuTime
}
```

4. **Check for no-op conditions**: Skip expensive operations when they won't change the result:
```java
if (pathMapper.isNoop()) {
  return new StringValue(name);
}
// ... expensive path mapping logic
```

5. **Use efficient collection operations**: Prefer built-in optimized methods over manual iteration:
```java
// Instead of manual filtering with singleton lists
// Use Iterables.filter to avoid allocation overhead
```

This approach reduces unnecessary CPU cycles, I/O operations, and memory allocations, leading to better overall performance.

---

## Cache expensive computations

<!-- source: microsoft/terminal | topic: Performance Optimization | language: C++ | updated: 2025-07-14 -->

Identify and cache the results of expensive operations that are computed repeatedly with the same inputs. This includes function calls, data structure creation, regex compilation, and complex calculations that don't change between invocations.

Common patterns to watch for:
- Repeated calls to the same expensive function with identical parameters
- Recreating the same data structures across multiple instances
- Recompiling regular expressions on each use
- Duplicate algorithmic work in related operations

Examples of optimization opportunities:

```cpp
// Before: Each CommandViewModel duplicates the same data
class CommandViewModel {
    IMap<ShortcutAction, hstring> _AvailableActionsAndNamesMap; // Duplicated across instances
};

// After: Share expensive data across instances
class CommandViewModel {
    static const IMap<ShortcutAction, hstring> _SharedActionsAndNames; // Computed once
};

// Before: Repeated expensive function calls
if (_WindowProperties.WindowName() != L"") {
    auto name = _WindowProperties.WindowName(); // Called again
}

// After: Cache the result
if (const auto windowName = _WindowProperties.WindowName(); !windowName.empty()) {
    // Use windowName variable
}

// Before: Regex compiled on every validation
void _validateRegex(const hstring& regex) {
    std::wregex{ regex.cbegin(), regex.cend() }; // Expensive compilation each time
}

// After: Cache compiled regex instances
static std::unordered_map<hstring, std::wregex> _regexCache;
```

This optimization is particularly important for operations in hot paths, UI updates, or when processing large datasets. Always measure performance impact to ensure the caching overhead doesn't exceed the benefits.

---

## Use established configuration patterns

<!-- source: microsoft/terminal | topic: Configurations | language: Other | updated: 2025-07-14 -->

When adding new configuration options or settings, leverage existing configuration frameworks and patterns rather than implementing custom solutions. This ensures consistency, reduces boilerplate code, and maintains alignment with established practices.

For settings, use the appropriate macro systems:
```cpp
// Instead of manual implementation
bool UseMicaAlt() const;
bool _useMicaAlt = false;

// Use the established macro pattern
#define MTSM_GLOBAL_SETTINGS_FIELDS(X) \
    X(bool, UseMicaAlt, "useMicaAlt", false)
```

For configuration files, follow existing patterns in the codebase. When multiple variants are needed (like different Visual Studio editions), create separate configuration files following established naming conventions rather than trying to handle all cases in one file.

Avoid runtime configuration decisions that should be compile-time. Configuration values should not be exposed broadly with generic names, and branding-specific code should be compiled out rather than decided at runtime.

When adding new configuration options, ensure corresponding schema files and documentation are updated to maintain consistency across the system.

---

## prefer const declarations

<!-- source: microsoft/terminal | topic: Code Style | language: C++ | updated: 2025-07-14 -->

Use `const` for variables that are not modified after initialization, and avoid creating unnecessary temporary variables when the value can be computed directly in the declaration.

This improves code clarity by making immutability explicit and reduces cognitive load by eliminating intermediate variables that don't add semantic value.

**Examples:**

```cpp
// Preferred
const auto paneActiveBorderColor = theme.Pane() ? theme.Pane().ActiveBorderColor() : nullptr;
const auto setter = setterBase.as<winrt::Windows::UI::Xaml::Setter>();
const auto property = setter.Property();

// Avoid
auto paneActiveBorderColor = theme.Pane() ? theme.Pane().ActiveBorderColor() : nullptr;
const bool isAudibleSet = WI_IsFlagSet(bellStyle, BellStyle::Audible);
const bool isWindowSet = WI_IsFlagSet(bellStyle, BellStyle::Window);
// ... later using these bools
if (isAudibleSet && isWindowSet) // Instead, use direct flag checks
```

For parameter passing, prefer `const&` over copying when the parameter won't be modified, or use move semantics when transferring ownership. Avoid the `auto{}` brace-initialization syntax as it can be brittle and is not widely adopted in the ecosystem.

---

## API parameter explicitness

<!-- source: microsoft/terminal | topic: API | language: C++ | updated: 2025-07-14 -->

Always use correct and explicit parameters when calling APIs, rather than relying on defaults or passing incorrect values. This includes passing appropriate objects to API methods, specifying all required parameters explicitly, and using correct operation patterns.

Key practices:
- Pass the correct object references to API methods (e.g., `nullptr` instead of `*this` when documentation suggests it)
- Always provide explicit parameters for programmatic operations, especially when dealing with external tools or services
- Use proper operation patterns (e.g., pre-increment `--iterator` when you don't need the previous result)
- Prefer efficient API methods when available (e.g., `ReplaceAll()` instead of `Clear()` followed by multiple `Append()` calls)

Example from the codebase:
```cpp
// Instead of passing potentially incorrect object reference
eventArgs.GetCurrentPoint(*this).Properties().IsMiddleButtonPressed()

// Pass the correct parameter as documented
eventArgs.GetCurrentPoint(nullptr).Properties().IsMiddleButtonPressed()

// For programmatic operations, always specify explicit parameters
profile->Commandline(winrt::hstring{ 
    fmt::format(FMT_COMPILE(L"cmd /k winget install --interactive --id Microsoft.PowerShell --source winget & echo. & echo {} & exit"), 
    RS_(L"PowerShellInstallationInstallerGuidance")) 
});
```

This approach reduces bugs, improves maintainability, and ensures APIs behave as intended rather than relying on potentially fragile default behaviors.

---

## optimize React rerenders

<!-- source: microsoft/playwright | topic: React | language: TSX | updated: 2025-07-14 -->

Ensure React components avoid unnecessary rerenders by maintaining object identity in dependencies and eliminating unused state variables. When objects are recreated on every render, they cause effects and child components to re-execute unnecessarily, leading to performance issues.

Key practices:
- Use `useMemo` to maintain object identity for effect dependencies when the underlying data hasn't changed
- Remove state variables that don't contribute to rendering decisions, as they trigger rerenders without benefit
- Consider state stability when designing data structures - avoid creating new objects every render cycle

Example of the problem:
```js
// Bad: Creates new object every render, causing effect to run unnecessarily
const snapshotUrls = {
  snapshotInfoUrl: snapshot?.url
};

React.useEffect(() => {
  // This runs on every render due to new snapshotUrls object
}, [snapshotUrls]);

// Good: Memoize to maintain object identity
const snapshotUrls = React.useMemo(() => ({
  snapshotInfoUrl: snapshot?.url
}), [snapshot?.url]);
```

Also avoid state variables used only for calculations:
```js
// Bad: Unnecessary state that causes rerenders
const [containerWidth, setContainerWidth] = React.useState(0);

// Good: Use ref or calculate directly if not needed for rendering
const containerRef = React.useRef();
```

---

## Avoid CSS !important

<!-- source: microsoft/vscode | topic: Code Style | language: Css | updated: 2025-07-14 -->

Using `!important` in CSS declarations should be avoided as it makes styles difficult to override and maintain. Instead, use more specific selectors to achieve the desired styling hierarchy. This improves code maintainability and follows CSS best practices.

For example, instead of:
```css
.monaco-workbench .part.editor > .content .gettingStartedContainer .test-banner {
  background: linear-gradient(45deg, #ff6b6b, #4ecdc4) !important;
  color: white !important;
}
```

Prefer using more specific selectors:
```css
.monaco-workbench .part.editor > .content .gettingStartedContainer .test-banner.special-banner {
  background: linear-gradient(45deg, #ff6b6b, #4ecdc4);
  color: white;
}
```

This approach ensures styles can be more easily maintained, understood, and overridden when necessary without creating specificity wars in your stylesheets.

---

## Provide helpful documentation context

<!-- source: neovim/neovim | topic: Documentation | language: Txt | updated: 2025-07-13 -->

Documentation should include sufficient context, practical examples, and helpful hints to make it truly useful for developers. Avoid assuming users have background knowledge - explain concepts, provide examples, and mention related functionality.

Key practices:
- Explain technical terms and concepts (e.g., "what is a linked editing session?")
- Include practical examples and usage hints (e.g., "`:EditQuery <tab>` completes injected language names")
- Show command examples with common options (e.g., "+cmd examples for restart")
- Mention features in all relevant documentation locations, not just one place
- Ensure documentation positioning matches its actual complexity level

Example of good contextual documentation:
```
:restart[!] [+cmd]                                              *:restart*
    Restart Nvim. This fails when changes have been made. 
    Use :confirm restart to override.
    
    Examples:
        :restart +PluginUpdate    " Restart and run command
        :confirm restart          " Restart with change confirmation
```

This approach transforms documentation from mere reference material into genuinely helpful guidance that reduces the learning curve for users.

---

## Conditional expensive operations

<!-- source: neovim/neovim | topic: Performance Optimization | language: Other | updated: 2025-07-13 -->

Only execute expensive operations when they are actually necessary. Avoid paying performance costs for functionality that may not be used or when conditions don't require the expensive computation.

Key strategies:
- **Conditional execution**: Wrap expensive calls in conditions that check if the operation is needed
- **Lazy loading**: Defer expensive initialization until actually required  
- **Demand-based setup**: Only set up costly event handlers or processing when the feature is actively used

Examples:

```lua
-- Bad: Always pay the fs_stat cost
local stat = vim.uv.fs_stat(f)

-- Good: Only pay the cost when needed
if follow_param then
  local stat = vim.uv.fs_stat(f)
end

-- Bad: Eager loading causes performance hit
complete = vim.treesitter.language._complete,

-- Good: Lazy loading avoids eager initialization
complete = function(...) return vim.treesitter.language._complete(...) end,

-- Bad: Everyone pays the cost regardless of usage
vim.api.nvim_create_autocmd('DiagnosticChanged', {
  callback = function() -- expensive string formatting end
})

-- Good: Only setup when default statusline is used
if using_default_statusline then
  vim.api.nvim_create_autocmd('DiagnosticChanged', {
    callback = function() -- expensive string formatting end
  })
end
```

This approach prevents unnecessary performance overhead by ensuring expensive operations are only executed when their results will actually be used or when the conditions genuinely require them.

---

## Configuration variable organization

<!-- source: neovim/neovim | topic: Configurations | language: Other | updated: 2025-07-13 -->

Use structured naming patterns and avoid polluting the global namespace when managing configuration variables. Prefer storing configuration state on relevant objects rather than creating numerous top-level global variables.

For naming patterns, use separators like ":" to distinguish variable components:
```lua
-- Good: structured naming with clear separation
local function get_client_augroup(client_id)
  return 'nvim.lsp.linked_editing_range.client:' .. client_id
end
```

When dealing with client-specific or feature-specific configuration, consider storing the data directly on the relevant object instead of creating many global variables:
```lua
-- Instead of: many global variables like __lsp_feature_client_42_enabled
-- Prefer: storing on the client object itself
client._feature_enabled = true
```

For complex configuration hierarchies, use nested tables rather than flat naming schemes:
```lua
-- Good: organized structure
_lsp_enable = {
  client = { [42] = true, [78] = true },
  feature = { hover = true, completion = false }
}

-- Avoid: namespace pollution
-- __lsp_hover_client_42_enabled = true
-- __lsp_completion_client_78_enabled = false
```

This approach reduces global namespace pollution, improves code maintainability, and makes configuration relationships more explicit.

---

## Use descriptive names

<!-- source: neovim/neovim | topic: Naming Conventions | language: C | updated: 2025-07-13 -->

Avoid ambiguous or vague identifiers in favor of specific, self-documenting names that clearly convey purpose and context.

Names should be immediately understandable without requiring additional context or documentation. Generic terms like "float" should be replaced with specific terms like "floatwin" or "win_float" to eliminate ambiguity. Function names should clearly indicate their action and scope.

Examples of improvements:
- `parse_float_option()` → `win_float_parse_option()` or `parse_previewpopup_option()`
- `get_current_prompt()` → `prompt_gettext()` or `prompt_cur_input()`
- Dictionary keys: `"wintype"` with value `"cmdwin"` instead of single-character codes
- API fields should be self-documenting: `wintype=="cmdwin"` is clearer than checking `strlen(wintype)==1`

This approach reduces cognitive load for developers, makes code more maintainable, and prevents confusion about identifier scope and purpose. When multiple similar functions exist, ensure names clearly distinguish their specific use cases rather than creating generic catch-all names.

---

## Lazy initialization patterns

<!-- source: zen-browser/desktop | topic: Performance Optimization | language: Other | updated: 2025-07-13 -->

Avoid repeatedly performing expensive operations like adding event handlers, loading resources, or fetching preferences. Instead, initialize these resources once when first needed and reuse them thereafter. This prevents memory leaks, reduces unnecessary work, and improves performance.

Key principles:
- Initialize event handlers during component setup, not in frequently-called methods
- Load scripts and resources on-demand rather than eagerly
- Cache preference values using lazy observers instead of fetching repeatedly

Example of problematic code:
```javascript
openTabsPopup(event) {
  // BAD: Adds new event handler every time popup opens
  search.addEventListener('input', () => {
    // handler logic
  });
  
  // BAD: Fetches preference on every call
  if(Services.prefs.getBoolPref("zen.some-pref", false)) {
    // logic
  }
}
```

Better approach:
```javascript
constructor() {
  // Initialize event handlers once during setup
  this.#setupEventHandlers();
  // Setup lazy preference observer
  this.#setupPrefObserver();
}

loadResourcesOnDemand() {
  if (!this.#resourcesLoaded) {
    Services.scriptloader.loadSubScript("chrome://browser/content/resource.mjs", this);
    this.#resourcesLoaded = true;
  }
}
```

---

## Optimize query performance

<!-- source: helix-editor/helix | topic: Algorithms | language: Other | updated: 2025-07-13 -->

When writing tree-sitter queries, prioritize performance by choosing efficient predicates and avoiding computationally expensive operations. Use `#any-of?` instead of complex `#match?` patterns when checking against multiple literal values, as it reduces regex compilation overhead. Avoid predicates like `#has-ancestor?` which have poor performance characteristics due to unbounded tree traversal. Consider the computational complexity of your queries, especially for features that run frequently like syntax highlighting during scrolling.

Example of optimization:
```
; Instead of expensive regex matching:
((identifier) @variable.builtin
 (#match? @variable.builtin "^(this|msg|block|tx)$"))

; Use efficient literal matching:
((identifier) @variable.builtin 
 (#any-of? @variable.builtin "this" "msg" "block" "tx"))
```

For performance-critical features, ensure optimized builds are used and consider caching strategies when queries involve expensive calculations that run repeatedly during user interactions.

---

## centralize workspace dependencies

<!-- source: alacritty/alacritty | topic: Configurations | language: Toml | updated: 2025-07-13 -->

Define shared dependencies at the workspace level in the root Cargo.toml to ensure version consistency and prevent conflicts across the project. This approach centralizes dependency management and makes it easier to maintain uniform versions throughout the codebase.

When multiple crates in your workspace use the same dependency, declare it in the workspace dependencies section and reference it from individual crates. This prevents version mismatches and reduces the risk of using unmaintained or conflicting dependency versions.

Example:
```toml
# Root Cargo.toml
[workspace.dependencies]
toml = "0.9.2"
toml_edit = "0.23.1"
dirs = "2.0"  # Use consistent version across workspace

# Individual crate Cargo.toml
[dependencies]
toml = { workspace = true }
dirs = { workspace = true }
```

This practice is especially important when dealing with dependencies that have breaking changes between major versions or when some dependencies are unmaintained and you need to stick with specific stable versions across your entire workspace.

---

## Document connection scope

<!-- source: neovim/neovim | topic: Networking | language: Txt | updated: 2025-07-13 -->

When documenting network connection operations, clearly specify the scope of when operations are supported and their limitations. Include information about initial connection requirements, fallback behaviors, and unsupported scenarios to help users understand operational boundaries.

For connection management commands, document:
- Prerequisites (e.g., "This only works if the UI started the server initially")
- Fallback behaviors (e.g., "this command is equivalent to |:detach|")
- Unsupported scenarios (e.g., "If the UI connected to some random remote endpoint, that is out of scope")

Example:
```
:connect {address}
                Detaches the UI from the server it is currently attached to
                and attaches it to the server at {address} instead.

                Note: If the current UI hasn't implemented the "connect" UI
                event, this command is equivalent to |:detach|.
```

This prevents user confusion and sets proper expectations about connection operation capabilities and constraints.

---

## optimize algorithm choices

<!-- source: bazelbuild/bazel | topic: Algorithms | language: Java | updated: 2025-07-12 -->

Choose algorithms and data structures that provide both deterministic behavior and optimal performance characteristics. Prefer ordered collections when iteration order matters, optimize pattern matching to avoid expensive operations, and be mindful of algorithmic complexity.

Key principles:
- Use deterministic data structures (e.g., `std::set` instead of `unsorted_set`, `ImmutableListMultimap` instead of custom maps) to ensure consistent output
- Optimize pattern matching by converting complex regex patterns to simpler string operations when possible: "If the pattern matches a literal suffix, optimize to a string suffix match, which is by far the fastest way to match"
- Preserve ordering semantics when filtering collections rather than treating them as unordered sets
- Avoid quadratic complexity algorithms, especially in scenarios with large N where "iterating over the packages and then over each mapping's entries would thus require time quadratic in N"
- Consider string containment (`indexOf`) over regex patterns for simple substring matching

Example optimization:
```java
// Instead of complex regex for simple suffix matching
if (LITERAL_PATTERN_WITH_DOT_UNESCAPED.matcher(suffixPattern).matches()) {
  String literalSuffix = suffixPattern.replace("\\.", ".");
  return s -> s.endsWith(literalSuffix);  // Much faster than regex
}

// Use ordered collections for deterministic behavior
ImmutableListMultimap<Label, SpawnStrategy> platformToStrategies;  // Preserves order
// Instead of: Map<Label, List<SpawnStrategy>>
```

This approach ensures both correctness through deterministic behavior and performance through algorithmic efficiency.

---

## Semantic identifier naming patterns

<!-- source: helix-editor/helix | topic: Naming Conventions | language: Other | updated: 2025-07-12 -->

Use consistent naming patterns that reflect the semantic role of identifiers:

1. Constants should use UPPER_SNAKE_CASE:
```
const MAX_RETRY_COUNT = 3;
const API_BASE_URL = "https://api.example.com";
```

2. Type names should use TitleCase:
```
struct UserProfile { }
class DatabaseConnection { }
```

3. Functions/methods should use camelCase:
```
fn calculateTotal() { }
fn validateUserInput() { }
```

4. Member variables should use a consistent prefix (e.g., m_) to clearly identify class/struct members:
```
struct Widget {
    m_width: i32,
    m_height: i32
}
```

This pattern makes code more readable by allowing quick visual identification of an identifier's role. It also helps catch semantic errors where identifiers might be used incorrectly (e.g., using a type name where a function was intended).

---

## Use descriptive contextual names

<!-- source: alacritty/alacritty | topic: Naming Conventions | language: Rust | updated: 2025-07-11 -->

Choose variable, function, and struct names that clearly communicate their purpose and content while considering their surrounding context. Avoid generic names like `x`, `normal`, or `data` that provide no semantic meaning. When naming within a specific scope or module, avoid redundant prefixes that repeat the context.

**Bad examples:**
```rust
// Generic, meaningless names
let x = error_result;
let normal = should_use_standard_input;
let first_line = column_count; // Misleading content

// Redundant context
struct WindowConfig {
    pub window_level: WindowLevel, // "window" is redundant
}

// Implementation-focused naming
pub fn try_from_textual(&self) -> Option<SequenceBase> // Doesn't return Self
```

**Good examples:**
```rust
// Descriptive, purpose-driven names
let err = error_result;
let use_standard_input = should_use_standard_input;
let column_count = first_line_columns;

// Context-aware naming
struct WindowConfig {
    pub level: WindowLevel, // Context is clear from struct name
}

// Semantic naming
pub fn try_build_textual(&self) -> Option<SequenceBase> // Clear about what it builds
```

Consider the scope and context when naming - a variable named `level` inside a `WindowConfig` is clearer than `window_level`. Use domain-specific terminology that your team understands, and prefer full words over abbreviations unless the abbreviation is universally recognized in your domain (like `fd` for file descriptor).

---

## optimize algorithmic efficiency

<!-- source: alacritty/alacritty | topic: Algorithms | language: Rust | updated: 2025-07-11 -->

Eliminate unnecessary operations and choose appropriate data structures to improve algorithmic efficiency. Look for opportunities to remove redundant computations, avoid unnecessary allocations, and leverage built-in methods instead of manual implementations.

Key areas to focus on:

1. **Remove unnecessary safety operations** when bounds are guaranteed. For example, avoid `saturating_sub` when the subtraction cannot underflow:
```rust
// Instead of this when bounds are guaranteed:
let middle_lines = total_lines.saturating_sub(1);

// Use this:
let middle_lines = total_lines - 1;
```

2. **Use built-in iterator methods** instead of manual iteration:
```rust
// Instead of manual zip:
for (p1, p2) in iter::zip(f_x, g_x) {

// Use built-in zip:
for (p1, p2) in f_x.zip(g_x) {
```

3. **Choose appropriate data structures** based on known constraints. Use fixed-size arrays instead of dynamic vectors when the maximum size is known and small:
```rust
// Instead of Vec for known small collections:
let uris: Vec<Vec<char>> = self.highlighted_hint.iter()...

// Consider fixed-size alternatives when applicable
```

4. **Avoid duplicate iterations** by combining operations or using more efficient algorithms:
```rust
// Instead of iterating twice to find byte and char indices:
if let Some(mut index) = self.state.find("://") {
    for (char_index, (byte_index, _)) in self.state.char_indices().enumerate() {
        if byte_index == index { index = char_index; break; }
    }

// Use char_indices directly with appropriate logic
```

5. **Simplify mathematical expressions** to reduce computational overhead and improve readability:
```rust
// Instead of complex division chains:
1_000_000 / (60_000 / 1000)

// Use simplified form:
1_000_000_000 / 60_000
```

6. **Optimize conditional logic** by restructuring boolean expressions for better performance and clarity:
```rust
// Instead of:
if uniq_hyperlinks.contains(&hyperlink) {
    return None;
}
uniq_hyperlinks.insert(hyperlink.clone());
Some((cell, hyperlink))

// Use:
if !uniq_hyperlinks.contains(&hyperlink) {
    uniq_hyperlinks.insert(hyperlink.clone());
    Some((cell, hyperlink))
} else {
    None
}
```

These optimizations improve both performance and code maintainability while reducing the likelihood of algorithmic inefficiencies.

---

## Handle errors with specificity

<!-- source: microsoft/vscode | topic: Error Handling | language: TypeScript | updated: 2025-07-11 -->

Always handle errors specifically and explicitly, avoiding generic catch blocks that mask or ignore errors. Ensure proper resource cleanup and consistent error propagation. Key practices:

1. Match specific error conditions instead of using catch-all blocks
2. Clean up resources even in error paths
3. Propagate errors appropriately rather than swallowing them
4. Handle errors consistently across similar scenarios

Example of proper error handling:

```typescript
private async getWorktreesFS(): Promise<Worktree[]> {
    const worktreesPath = path.join(this.repositoryRoot, '.git', 'worktrees');
    try {
        const raw = await fs.readdir(worktreesPath);
        // ... processing ...
    } catch (err) {
        // Handle specific error condition
        if (/ENOENT/.test(err.message)) {
            return [];
        }
        // Propagate unexpected errors
        throw err;
    } finally {
        // Clean up resources
        this.disposables.dispose();
    }
}
```

Bad practice to avoid:
```typescript
try {
    // ... operations ...
} catch (err) {
    // DON'T: Silently swallow errors
}
```

---

## Semantic naming over implementation

<!-- source: neovim/neovim | topic: Naming Conventions | language: Txt | updated: 2025-07-11 -->

Choose names that reflect the semantic purpose and meaning rather than implementation details or internal mechanisms. Names should communicate what something does or represents from the user's perspective, not how it works internally.

For example, prefer `on_response` over `on_exit` for HTTP request callbacks, since "response" describes the semantic event while "exit" exposes the internal detail that curl process exits. Similarly, use `version` to describe the semantic concept rather than `checkout` which exposes the Git implementation detail.

Follow established project conventions consistently:
- Use `on_` prefix for event-handling callbacks and handlers
- Use `callback` for continuation functions (single callback parameter)
- Apply naming patterns systematically across similar contexts

Example of good semantic naming:
```lua
-- Good: describes the semantic purpose
vim.net.request(url, opts, on_response)

-- Poor: exposes implementation detail  
vim.net.request(url, opts, on_exit)
```

When multiple naming options exist, prioritize the one that best communicates the intended use and meaning to other developers, while maintaining consistency with existing codebase patterns.

---

## Protocol-specific network handling

<!-- source: electron/electron | topic: Networking | language: Other | updated: 2025-07-11 -->

When implementing custom network protocol behavior, ensure that modifications are properly scoped to only the intended protocol types and include upstream context documentation. Avoid applying protocol-specific changes broadly across all network protocols, as this can break assumptions and cause unintended side effects.

Key principles:
1. **Scope restrictions appropriately**: Limit custom behavior to specific protocol types that require it, rather than applying changes universally
2. **Document upstream context**: Include references to upstream changes and their motivations in patch files for future maintainability
3. **Align with upstream behavior**: Keep behavior consistent with upstream implementations except where explicitly needed for specific protocols

Example from streaming protocol handling:
```cpp
// Good: Scoped to streaming custom protocols only
if (IsStreamingCustomProtocol(url)) {
  destination_url_data->set_range_supported();
}

// Avoid: Broad application that could break other protocols
destination_url_data->set_range_supported(); // Applied to all protocols
```

When modifying network service initialization, ensure proper guards are in place:
```cpp
SystemNetworkContextManager* SystemNetworkContextManager::GetInstance() {
  if (!g_system_network_context_manager) {
    content::GetNetworkService();
    DCHECK(g_system_network_context_manager);
  }
  return g_system_network_context_manager;
}
```

This approach prevents breaking buffering assumptions for protocols like file:// URLs while enabling the required functionality for custom streaming protocols that support range requests.

---

## Validate before expensive operations

<!-- source: microsoft/vscode | topic: Performance Optimization | language: TypeScript | updated: 2025-07-10 -->

Perform lightweight validation checks before executing expensive operations to avoid unnecessary resource consumption. This is especially important in hot paths or frequently called functions.

Key practices:
1. Use file system operations instead of process spawning
2. Check file sizes before reading entire files
3. Filter collections before heavy processing
4. Use specific API methods instead of broad queries

Example - Before:
```typescript
async function getWorktrees(): Promise<Worktree[]> {
    // Spawns process on hot path
    const result = await spawn('git', ['worktree', 'list']);
    return parseWorktrees(result);
}
```

After:
```typescript
async function getWorktrees(): Promise<Worktree[]> {
    // Use fs operations first
    const hasWorktrees = await fs.exists('.git/worktrees');
    if (!hasWorktrees) {
        return [];
    }
    // Only spawn process if needed
    const result = await spawn('git', ['worktree', 'list']);
    return parseWorktrees(result);
}
```

---

## prevent autocommand reentrancy

<!-- source: neovim/neovim | topic: Concurrency | language: C | updated: 2025-07-10 -->

Guard against reentrancy issues when operations may trigger autocommands or async events that could invalidate state or cause recursive execution. Check for existing execution context before proceeding and validate that pointers/state remain valid after operations that may trigger autocommands.

Key practices:
1. **Check execution state early**: Before operations that may trigger autocommands, check if similar operations are already running and fail with clear error messages
2. **Validate state after autocommands**: After operations like `win_new_tabpage()` or `win_set_buf()`, verify that pointers and handles are still valid before using them
3. **Use proper event scheduling**: For operations that must be deferred, use mechanisms like `multiqueue_put()` to schedule on appropriate event loops rather than blocking

Example from the codebase:
```c
// Check for reentrancy before proceeding
if (in_filetype_autocmd()) {
    api_set_error(err, kErrorTypeException,
                  "Cannot detect default while FileType autocommands are running");
    return;
}

// After operations that trigger autocommands, validate state
tabpage_T *tp = win_new_tabpage(after, buf->b_ffname, enter);
if (!tp) {
    // tp may have been freed by autocommands
    api_set_error(err, kErrorTypeException, "Failed to create tabpage");
    return 0;
}
// Validate tp->tp_firstwin is still valid before using
```

This prevents race conditions where autocommands modify global state during API operations, leading to crashes or data corruption.

---

## Clear actionable error messages

<!-- source: python-poetry/poetry | topic: Error Handling | language: Python | updated: 2025-07-09 -->

Error messages should be user-friendly, readable, and provide actionable guidance for resolution. Avoid exposing technical implementation details like raw dictionaries, regex patterns, or internal data structures to end users. Instead, format errors clearly and include specific steps users can take to resolve the issue.

When validation fails or errors occur, provide context about what went wrong and suggest concrete next steps. For example, instead of showing raw validation output like `{'errors': ['project.name must match pattern ^([a-zA-Z\\d]|[a-zA-Z\\d][\\w.-]*[a-zA-Z\\d])$']}`, format it as:

```python
# Bad - exposes technical details
self.line_error(f"<error>Validation failed: {validation_results}</error>")

# Good - clear and actionable
self.line_error(
    "<error>"
    "Error: poetry.lock is not consistent with pyproject.toml. "
    "Run `poetry lock [--no-update]` to fix it."
    "</error>"
)
```

Consider your audience - error messages should be understandable by developers of all experience levels. When technical details are necessary, provide them in debug/verbose modes while keeping the default error message focused on what the user needs to do to resolve the issue.

---

## Use if-unwrap with optionals

<!-- source: ghostty-org/ghostty | topic: Null Handling | language: Other | updated: 2025-07-09 -->

Always use Zig's if-unwrap pattern (`if (optional) |value| {...}`) when working with optional values instead of forced unwrapping with `.?`. This pattern is safer as it avoids runtime panics, more readable, and aligns with Zig's idioms for null safety.

When checking an optional only to see if it's not null and discarding the value, use `!= null` instead of additional syntax. When you need to use the value, use the if-unwrap pattern to create a new non-optional variable in a limited scope:

```zig
// Bad - prone to crashes if null
if (self.current_background_image != null) {
    switch (self.current_background_image.?) {
        .ready => {},
        // ...
    }
}

// Good - compiler enforced null safety
if (self.current_background_image) |current_background_image| {
    switch (current_background_image) {
        .ready => {},
        // ...
    }
}

// Bad - will crash if background-image is null
const background_image = try config.@"background-image".?.clone(alloc);

// Good - handles null case explicitly
const background_image = if (config.@"background-image") |v| try v.clone(alloc) else null;

// Alternative approach - early return
const current_background_image = self.current_background_image orelse return;
// Now use current_background_image without unwrapping
```

This approach not only prevents runtime crashes but also makes the code's intent clearer and leverages the compiler's ability to enforce null safety.

---

## weak pointer callback safety

<!-- source: hyprwm/Hyprland | topic: Concurrency | language: C++ | updated: 2025-07-09 -->

When capturing objects in callbacks or lambdas that may execute asynchronously, use weak pointers instead of raw pointers or shared pointers to prevent use-after-free bugs. Always validate the weak pointer before dereferencing it, and avoid redundant lock() calls on the same weak pointer.

This pattern is essential for thread safety when objects may be destroyed while callbacks are still pending execution. The weak pointer allows the callback to safely check if the object still exists before attempting to use it.

Example of proper weak pointer usage in callbacks:
```cpp
// Good: Use weak pointer and validate before use
auto weakBuffer = WP<IHLBuffer>(PBUFFER);
PBUFFER->onBackendRelease([weakBuffer]() {
    if (auto buffer = weakBuffer.lock())
        buffer->unlock();
});

// Avoid: Redundant lock() calls in comparisons
if (weakPtr1.lock() == weakPtr2.lock()) // redundant double .lock()
// Better: Store locked pointers if comparing multiple times
auto ptr1 = weakPtr1.lock();
auto ptr2 = weakPtr2.lock();
if (ptr1 == ptr2)
```

This approach prevents crashes when the referenced object is destroyed before the callback executes, which is common in asynchronous systems with complex object lifetimes.

---

## avoid Lua ternary traps

<!-- source: neovim/neovim | topic: Null Handling | language: Other | updated: 2025-07-09 -->

Avoid using the `condition and expr1 or expr2` pattern when `expr1` can be `nil` or `false`, as this will always return `expr2` regardless of the condition result. This is a common source of subtle bugs in Lua code.

The pattern `condition and expr1 or expr2` only works correctly when `expr1` is guaranteed to be truthy. When `expr1` can be `nil` or `false`, the `or expr2` part will always execute, making the condition meaningless.

**Problematic examples:**
```lua
-- This will always return `enable`, never `nil`
vim.b[bufnr][var] = enable == vim.g[var] and nil or enable

-- This fails when enable is false
bufstate.enabled = enable ~= globalstate.enabled and enable or nil
```

**Safe alternatives:**
```lua
-- Use explicit if-else
if enable == vim.g[var] then
  vim.b[bufnr][var] = nil
else
  vim.b[bufnr][var] = enable
end

-- Use vim.F.if_nil for nil-specific cases
result = vim.F.if_nil(potentially_nil_value, fallback)
```

This pattern is particularly dangerous because it appears to work correctly in many cases, making the bug difficult to detect during testing.

---

## Verify test commands

<!-- source: vercel/turborepo | topic: Testing | language: Markdown | updated: 2025-07-08 -->

Always verify that test commands documented in project guides work exactly as written. Test commands should be copy-paste executable without modification. When adding or updating test command examples in documentation:

1. Execute the exact command from a clean environment before committing changes
2. Include complete command syntax with all necessary flags
3. Specify expected behavior or output when relevant

**Example:**
```bash
# ✅ GOOD: Complete, verified command
cargo coverage -- --open  # Runs tests with coverage and opens the report

# ❌ BAD: Incorrect command syntax
cargo run --bin coverage -- --open  # May not work in all environments
```

For integration tests that target specific files or tests:

```bash
# ✅ GOOD: Correctly specifies how to run a specific test
pnpm --filter turborepo-tests-integration test tests/turbo-help.t

# ❌ BAD: Incorrect or platform-dependent command
pnpm test:interactive -F turborepo-tests-integration -- run-summary.t
```

This practice ensures developers can efficiently run tests without debugging documentation issues first.

---

## Document configuration specifics

<!-- source: alacritty/alacritty | topic: Configurations | language: Markdown | updated: 2025-07-07 -->

When documenting configuration options in changelogs, README files, or other user-facing documentation, focus on specific implementation details and user-actionable information rather than vague feature descriptions. Write from the user's perspective, specifying exact configuration keys, values, and behaviors.

Key principles:
- Include actual config option names and example values
- Describe what the user will experience, not internal implementation details
- Use precise, implementation-specific language over generic descriptions
- Focus on user benefits and practical usage

Examples:
- Instead of: "Add additional fallback under `/etc/alacritty/alacritty.toml` for system wide configuration"
- Write: "Add `/etc/alacritty/alacritty.toml` fallback for system wide configuration"

- Instead of: "Shell initialization on macOS to manually check the `~/.hushlogin` file"  
- Write: "Pass `-q` to `login` on macOS if `~/.hushlogin` is present"

- Instead of: "window.level sets preferred window level (Normal, AlwaysOnTop)"
- Write: "Config option `window.level = "AlwaysOnTop"` to force Alacritty to always be the toplevel window"

Remember: "We don't document things for developers, we document them for users." Configuration documentation should help users understand exactly what to configure and what behavior to expect.

---

## Robust SSH integration

<!-- source: ghostty-org/ghostty | topic: Networking | language: Other | updated: 2025-07-07 -->

When implementing SSH integration in your application, follow these practices to ensure reliability across different systems:

1. **Preserve user context**: Include user information in SSH target identification, as many operations (like terminfo installation) write to user-specific directories.

```bash
# AVOID: Only capturing hostname
ssh_hostname="$(ssh -G "$@" | grep hostname | cut -d' ' -f2)"

# BETTER: Capture full user@host target
ssh_config=$(ssh -G "$@" 2>/dev/null)
while IFS=' ' read -r key value; do
  case "$key" in
    user) ssh_user="$value" ;;
    hostname) ssh_hostname="$value" ;;
  esac
done < <(ssh -G "$@" 2>/dev/null)
ssh_target="${ssh_user}@${ssh_hostname}"
```

2. **Minimize environment changes**: Avoid modifying the local environment when possible. For environment variable overrides, set them at the command level instead of exporting and restoring:

```bash
# AVOID: Modifying and restoring environment
export TERM="$ssh_term_override"
command ssh "${ssh_opts[@]}" "$@"
export TERM="$original_term"

# BETTER: Override at command level
command TERM="$ssh_term_override" ssh "${ssh_opts[@]}" "$@"
```

3. **Clarify tool locations**: Document clearly which tools must exist locally versus remotely. For SSH operations like terminfo installation, be explicit about requirements:

```bash
# Local check (infocmp needed locally)
if ! command -v infocmp >/dev/null 2>&1; then
  echo "Warning: infocmp command not available locally for terminfo export." >&2
  return 1
fi

# Remote check (tic needed remotely)
if ! ssh "$host" "command -v tic >/dev/null 2>&1"; then
  echo "Warning: tic command not available on remote host for terminfo installation." >&2
  return 1
fi
```

4. **Use minimal commands**: Remove unnecessary operations in remote commands to improve reliability and performance:

```bash
# AVOID: Redundant commands
ssh "$host" 'mkdir -p ~/.terminfo/x 2>/dev/null && tic -x -o ~/.terminfo /dev/stdin'

# BETTER: Let tic handle directory creation
ssh "$host" 'tic -x - 2>/dev/null'
```

5. **Understand SSH options**: Use SSH options like SendEnv and SetEnv appropriately based on their behavior across different server configurations.

---

## Follow established API patterns

<!-- source: neovim/neovim | topic: API | language: Txt | updated: 2025-07-07 -->

APIs should follow documented conventions and established patterns within the codebase to ensure consistency and predictability. This includes adhering to naming conventions, parameter structures, and interface designs that users already expect.

Key patterns to follow:
- Use `enable(boolean)` pattern instead of separate `start()` and `stop()` functions
- Prefer filter kwargs tables over multiple individual parameters for extensibility
- Follow documented patterns in `:help dev-patterns` and `:help dev-naming`
- Maintain consistency with existing similar APIs in the same domain

Example of inconsistent API:
```lua
-- Inconsistent - uses start/stop pattern
vim.lsp.on_type_formatting.start(bufnr, client_id)
vim.lsp.on_type_formatting.stop(bufnr, client_id)

-- Inconsistent - individual parameters
enable(enable, bufnr, client_id)
```

Example of consistent API following established patterns:
```lua
-- Consistent - follows enable(boolean) pattern like other LSP features
vim.lsp.on_type_formatting.enable(true, {bufnr = bufnr, client_id = client_id})

-- Consistent - uses filter kwargs like other APIs
vim.lsp.linked_editing_range.enable(true, {bufnr = bufnr, client_id = client_id})
```

This consistency reduces cognitive load for users who can predict API behavior based on established patterns, and makes the codebase easier to maintain by following uniform conventions.

---

## Know your implicit configurations

<!-- source: vercel/turborepo | topic: Configurations | language: Other | updated: 2025-07-07 -->

When working with Turborepo, be aware of implicit configurations and special files that affect behavior even when not explicitly configured. For example, `turbo.json` and `package.json` are always considered inputs when determining if a package has changed, even if you try to explicitly ignore them. Package manager lockfiles are also always parsed and included in task hashes.

When setting up framework integrations in library packages, use `peerDependencies` in your `package.json` to make framework APIs available without direct installation:

```json
{
  "name": "@repo/ui",
  "peerDependencies": {
    "next": ">=15"
  }
}
```

Note that for older package managers, you may need to configure them to install peer dependencies or add the dependency to `devDependencies` as a workaround.

For repositories without a `packageManager` field, you can use `--dangerously-disable-package-manager-check` or set `dangerouslyDisablePackageManagerCheck: true` in `turbo.json` to bypass lockfile validation, but be aware this can lead to unpredictable behavior as Turborepo will attempt to discover the package manager through best-effort methods.

---

## optimize computational efficiency

<!-- source: hyprwm/Hyprland | topic: Algorithms | language: C++ | updated: 2025-07-07 -->

Prioritize algorithmic efficiency and avoid unnecessary computational overhead in performance-critical code paths. Look for opportunities to reduce time complexity and eliminate redundant calculations.

Key optimization strategies:
- Use squared distance instead of actual distance when only comparison is needed: `prefer distanceSq` over `distance()` for performance-critical geometric calculations
- Avoid nested loops when a single pass is sufficient: instead of O(rules × workspaces) complexity, optimize to O(rules) by tracking only changed elements
- Eliminate redundant calculations by caching or restructuring computation order
- Choose appropriate STL algorithms: use `std::erase_if` directly instead of the `std::ranges::remove_if` + `erase` pattern when possible

Example from distance calculations:
```cpp
// Instead of:
if (m_vBeginDragXY.distance(mousePos) <= *PDRAGTHRESHOLD)

// Use:
if (m_vBeginDragXY.distanceSq(mousePos) <= (*PDRAGTHRESHOLD * *PDRAGTHRESHOLD))
```

Example from workspace checking:
```cpp
// Instead of checking all workspaces against all rules O(n*m):
for (auto& workspace : workspaces) {
    for (auto& rule : rules) { /* check */ }
}

// Optimize to O(n) by checking only the changed workspace:
recheckPersistent(); // Only checks current workspace against rules
```

This approach reduces CPU cycles in frequently called functions and improves overall application responsiveness.

---

## Optimize comparison patterns efficiently

<!-- source: ghostty-org/ghostty | topic: Algorithms | language: Other | updated: 2025-07-07 -->

Choose efficient comparison patterns and algorithms based on the data type and use case. Key guidelines:

1. For string pattern matching, prefer glob patterns over regex for simple cases:
```zig
// Inefficient
if [[ "$FEATURES" =~ ssh-env ]]

// Efficient
if [[ "$FEATURES" == *ssh-env* ]]
```

2. For floating-point comparisons, use epsilon-based or range checks:
```zig
// Incorrect
if (opacity == 1.0)

// Correct
const epsilon = 1e-6;
if (@fabs(opacity - 1.0) < epsilon)
```

3. For version/order comparisons, use built-in comparison utilities:
```zig
// Verbose and error-prone
if (version.major > required.major ||
    (version.major == required.major && version.minor > required.minor))

// Cleaner and more efficient
return version.order(required) != .lt;
```

These patterns improve both code reliability and performance by using more appropriate comparison techniques for each data type.

---

## reuse concurrency infrastructure

<!-- source: neovim/neovim | topic: Concurrency | language: Other | updated: 2025-07-06 -->

Avoid implementing custom concurrency patterns when existing infrastructure is available. Before creating new debouncing, async/await, or parallel execution code, check if suitable implementations already exist in the codebase.

For example, instead of implementing a custom debounce function:

```lua
local function debunce(f, timeout)
  local timer = nil
  return function(...)
    local args = { ... }
    if timer then
      vim.uv.timer_stop(timer)
      timer:close()
      timer = nil
    end
    timer = assert(vim.uv.new_timer())
    vim.uv.timer_start(timer, timeout, 0, vim.schedule_wrap(function()
      if timer then
        vim.uv.timer_stop(timer)
        timer:close()
        timer = nil
      end
      f(unpack(args))
    end))
  end
end
```

Reuse existing debouncing infrastructure like `next_debounce` in `lsp/_changetracking.lua`. Similarly, prefer established async patterns like `vim.async.await(3, vim.system, cmd, opts)` over manual coroutine implementations.

This reduces code duplication, ensures consistent behavior across the codebase, and leverages battle-tested concurrency primitives that handle edge cases and performance optimizations.

---

## Pipeline-friendly script design

<!-- source: ghostty-org/ghostty | topic: CI/CD | language: Python | updated: 2025-07-06 -->

Design scripts to be easily integrated into build pipelines and CI/CD workflows by using standard I/O streams instead of hardcoded file paths. Scripts that read from stdin and write to stdout can be easily composed in pipelines, redirected, and incorporated into various build systems without modification.

Example - Before:
```python
if __name__ == "__main__":
    project_root = Path(__file__).resolve().parents[2]
    
    patcher_path = project_root / "vendor" / "nerd-fonts" / "font-patcher.py"
    source = patcher_path.read_text(encoding="utf-8")
    patch_set = extract_patch_set_values(source)
    
    out_path = project_root / "src" / "font" / "nerd_font_attributes.zig"
    # Write results to out_path
```

Example - After:
```python
import sys

if __name__ == "__main__":
    # Read from stdin if no arguments provided
    if len(sys.argv) > 1:
        with open(sys.argv[1], "r", encoding="utf-8") as f:
            source = f.read()
    else:
        source = sys.stdin.read()
        
    patch_set = extract_patch_set_values(source)
    
    # Write results to stdout
    print(generate_zig_output(patch_set))
```

This approach allows the script to be used in various CI contexts: `cat input.txt | python script.py > output.zig` or as part of more complex build rules without requiring code changes.

---

## API documentation precision

<!-- source: microsoft/playwright | topic: API | language: Markdown | updated: 2025-07-06 -->

API documentation must use specific, well-defined types instead of generic ones, and clearly define behavior for all scenarios including edge cases. When documenting return types, use explicit union types or named type aliases rather than generic strings. For complex APIs with multiple options, document the interaction between different parameters and their expected behavior.

For example, instead of:
```
- returns: <[string]>
```

Use specific union types:
```
- returns: <["log"|"debug"|"info"|"error"|"warning"|"dir"|"dirxml"|"table"|"trace"|"clear"|"startGroup"|"startGroupCollapsed"|"endGroup"|"assert"|"profile"|"profileEnd"|"count"|"timeEnd"]>
```

Or better yet, use named types:
```
- returns: <[ConsoleMessageType]>
```

Additionally, when introducing new API options, clearly document their behavior in all scenarios, especially when combined with other options or in edge cases. This prevents ambiguity and improves developer experience by making API contracts explicit and predictable.

---

## Descriptive consistent naming

<!-- source: ghostty-org/ghostty | topic: Naming Conventions | language: Other | updated: 2025-07-04 -->

Use descriptive, consistent naming that follows language and platform conventions. Choose names that clearly communicate purpose and context, and maintain consistency across similar elements.

For variables:
- Replace single-letter variables with descriptive names: 
  ```diff
  - local e=() o=() c=()
  + local env=() opts=() ctrl=()
  ```
- Add prefixes to indicate context or purpose:
  ```diff
  - local env=() opts=() ctrl=()
  + local ssh_env=() ssh_opts=() ssh_ctrl=()
  ```
- Follow language-specific conventions (Zig uses camelCase for functions, snake_case for variables):
  ```diff
  - pub fn wait_xev(
  + pub fn waitXev(
  
  - pub fn resourcesDir(alloc: Allocator, hostAccessible: bool)
  + pub fn resourcesDir(alloc: Allocator, host_accessible: bool)
  ```
- Use lowercase for enum values unless there's a reason not to:
  ```diff
  - pub const SetTitleSource = enum { USER, TERMINAL };
  + pub const SetTitleSource = enum { user, terminal };
  ```
- Use singular forms for type names:
  ```diff
  - pub const Dirs = enum {
  + pub const Dir = enum {
  ```
- Follow standard acronym casing conventions:
  ```diff
  - const updated = fixZHLocale(locale);
  + const updated = fixZhLocale(locale);
  ```

For APIs and actions:
- Use consistent naming patterns for related functionality:
  ```diff
  - .{ "command-palette", gtkActionToggleCommandPalette },
  + .{ "toggle-command-palette", gtkActionToggleCommandPalette },
  ```
- Choose names that match established terminology:
  ```diff
  - GHOSTTY_ACTION_BELL,
  + GHOSTTY_ACTION_RING_BELL,
  ```
- Use semantic names that match protocols or standards:
  ```diff
  - true,
  + none,
  ```

Choose names that balance brevity with clarity, and consider how names will be interpreted by other developers.

---

## Use extensible parameter objects

<!-- source: electron/electron | topic: API | language: Markdown | updated: 2025-07-04 -->

When designing APIs that may need additional parameters in the future, use objects instead of individual parameters to enable extension without breaking changes. This approach allows new properties to be added while maintaining backward compatibility.

Instead of adding individual parameters that create rigid function signatures:

```js
// Avoid: Hard to extend without breaking changes
win.setVibrancy(type, animate, animationDuration)
```

Use an options object that can accommodate future parameters:

```js
// Preferred: Extensible design
win.setVibrancy(type, {
  animate: boolean,
  animationDuration: number
  // Future properties can be added here
})
```

For events, group related parameters into a details object rather than individual parameters:

```js
// Avoid: Individual parameters
app.on('notification-activation', (event, appUserModelId, invokedArgs, dataCount, inputData) => {})

// Preferred: Details object
app.on('notification-activation', (event, details) => {
  // details.appUserModelId, details.invokedArgs, etc.
})
```

This pattern is especially important for APIs that interact with evolving web standards or platform capabilities, where new options frequently become available. Consider how Chrome extension APIs and DOM APIs use this pattern successfully - they can add new properties without breaking existing code that only uses a subset of the available options.

---

## use optional types safely

<!-- source: electron/electron | topic: Null Handling | language: Other | updated: 2025-07-04 -->

When functions may not return valid values, use `std::optional` or `absl::optional` instead of raw types that could represent invalid states. Always check the validity of optional values before accessing them to prevent null pointer dereferences and invalid value usage.

For functions that might fail or return invalid data, prefer optional return types:

```cpp
// Instead of returning 0 or invalid values on failure
std::optional<DWORD> GetAccentColor() {
  // ... implementation that may fail
  if (RegOpenKeyEx(...) != ERROR_SUCCESS) {
    return std::nullopt;  // Explicit failure indication
  }
  return accent_color;
}

// Always check validity before use
std::optional<DWORD> system_accent_color = GetAccentColor();
if (system_accent_color.has_value()) {
  border_color = RGB(GetRValue(system_accent_color.value()),
                     GetGValue(system_accent_color.value()),
                     GetBValue(system_accent_color.value()));
} else {
  should_apply_accent = false;
}
```

For pointer returns, check for null before dereferencing:

```cpp
auto* contents = electron::api::WebContents::From(web_contents);
return contents ? contents->ID() : -1;

// For optional pointers, use both checks
if (frame && frame.value()) {
  auto* frame_rfh = frame->render_frame_host();
  auto* rfh = frame_rfh ? frame_rfh->GetOutermostMainFrameOrEmbedder() : nullptr;
  if (rfh) {
    // Safe to use rfh
  }
}
```

This pattern prevents crashes from accessing invalid pointers or using sentinel values that could lead to unexpected behavior. Note that `base::Optional` has been deprecated in favor of `absl::optional` in newer codebases.

---

## Follow established naming patterns

<!-- source: Homebrew/brew | topic: Naming Conventions | language: Ruby | updated: 2025-07-04 -->

Names should be descriptive and consistent with existing patterns in the codebase. This applies to methods, variables, and DSL elements:

1. Follow existing naming patterns for similar concepts:
   ```ruby
   # Good: Follows pattern of post_install_defined?, resource_defined?
   def livecheck_defined?
     method(:livecheck).owner != Formula
   end

   # Bad: Inconsistent with existing pattern
   def has_livecheck?
     method(:livecheck).owner != Formula
   end
   ```

2. Use descriptive variable names that clearly indicate content:
   ```ruby
   # Good: Clear what the variable contains
   basename = File.basename(path, ".*")
   match_github = url.match(%r{github\.com/(?<user>\S+)/(?<repo>\S+)})

   # Bad: Unclear or ambiguous names
   m = url.match(%r{github\.com/(?<user>\S+)/(?<repo>\S+)})
   filename = File.basename(path, ".*") # When actually storing basename
   ```

3. For boolean methods, use question mark suffix and descriptive predicate:
   ```ruby
   # Good: Clear boolean nature and what's being checked
   def binary_linked_to_library?(binary, library)

   # Bad: Unclear if returns boolean
   def check_binary_linkage(binary, library)
   ```

---

## Ensure documentation accuracy

<!-- source: vitejs/vite | topic: Documentation | language: Markdown | updated: 2025-07-04 -->

Documentation must precisely reflect the current codebase implementation. When documenting features, options, or APIs:

1. Validate that all examples match the actual implementation. For instance, if template names or file formats change, update all references in the documentation:

```diff
- Package manager lockfile content, e.g. `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` or `bun.lockb`.
+ Package manager lockfile content, e.g. `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock`, or `bun.lockb`.
```

2. Remove outdated conditional language when options change. Instead of "can also be", use definitive statements that reflect current functionality:

```diff
- The value can also be an [options object] passed to `https.createServer()`.
+ The value is an [options object] passed to `https.createServer()`.
```

3. Remove deprecated parameters from examples and clarify their status in API references:

```diff
 interface ModuleRunnerOptions {
   /**
    * Root of the project
+   * @deprecated not used anymore and to be removed
    */
-  root: string
+  root?: string
 }
```

4. When updating or renaming APIs, ensure all documentation consistently uses the new terminology throughout. Maintaining accuracy builds user trust and prevents confusion when implementing features.

---

## Use descriptive consistent names

<!-- source: electron/electron | topic: Naming Conventions | language: Other | updated: 2025-07-04 -->

Choose names that are both semantically accurate and consistent with established patterns. Names should clearly convey their purpose, data type, and behavior while following existing conventions in the codebase and upstream dependencies.

Key principles:
- Use descriptive names that eliminate ambiguity about purpose (e.g., `CheckSwitchNameValid` returning an error message vs `IsSwitchNameValid` returning boolean)
- Match variable names to their data structure (e.g., `reasons` for a vector, not `reason`)
- Maintain consistent casing and formatting patterns within the same file or module
- Follow established external conventions when available (e.g., Chromium's "Fullscreen" as one word)
- Avoid names that could conflict with existing or future identifiers

Example:
```cpp
// Better: Descriptive and indicates return type
std::optional<std::string_view> CheckSwitchNameValid(std::string_view key) {
  if (!std::ranges::none_of(key, absl::ascii_isupper))
    return "Switch name must be lowercase";
  return {};
}

// Better: Plural name for collection parameter
void OnWindowEndSession(const std::vector<std::string> reasons) {
  // ...
}
```

---

## Secure configuration defaults

<!-- source: astral-sh/uv | topic: Configurations | language: Markdown | updated: 2025-07-04 -->

Establish secure default configurations in project metadata files to prevent accidental publishing and ensure proper version constraints. This is particularly important for private packages and build system configurations.

Key practices:
1. Add the "Private :: Do Not Upload" classifier for non-public packages:
```toml
[project]
classifiers = [
    "Private :: Do Not Upload",
    # Other classifiers...
]
```

2. Use appropriate version constraints in build system requirements:
```toml
[build-system]
# Prefer narrow version ranges for build backends
requires = ["uv>=0.4.18,<0.5"]
```

3. Validate completeness of required configuration fields:
- Ensure project.name is specified
- Include explicit version information
- Define clear build system requirements

This approach helps prevent accidental package uploads to public repositories and ensures reproducible builds through proper version constraints.

---

## Scope dependencies appropriately

<!-- source: zed-industries/zed | topic: Configurations | language: Toml | updated: 2025-07-04 -->

Configure dependencies with their minimum necessary scope to maintain clean architecture and improve build times. Key practices:

1. **Test-only dependencies should be dev-dependencies**
   If a dependency is only used for tests, add it as a dev-dependency and use `#[cfg(test)]` annotations:
   ```rust
   // Instead of adding to main Cargo.toml
   // unicode-width = "0.2"
   
   // Add to [dev-dependencies] section instead
   // And restrict usage to test code:
   #[cfg(test)]
   use unicode_width::UnicodeWidthStr;
   ```

2. **Keep core modules lightweight**
   Don't add heavy dependencies to utility or core modules. Move dependent code to appropriate modules:
   ```rust
   // Instead of this in util/Cargo.toml:
   // schemars.workspace = true
   
   // Create plain enums in util:
   pub enum SortStrategy {
       Lexicographical,
       Alphabetical,
   }
   
   // Then convert in settings module where JsonSchema is available
   ```

3. **Scope feature flags correctly**
   Define features at the appropriate module level rather than globally. For workspace-wide features, manage them centrally:
   ```toml
   # In workspace Cargo.toml:
   tokio = { version = "1.0", features = ["rt", "rt-multi-thread"] }
   
   # In module Cargo.toml:
   tokio.workspace = true
   ```

4. **Extract global configuration changes**
   When changing dependency configurations that affect multiple modules, consider making it a separate PR to properly evaluate the impact.

---

## Avoid redundant operations

<!-- source: microsoft/playwright | topic: Performance Optimization | language: TypeScript | updated: 2025-07-04 -->

Identify and eliminate duplicate computations, unnecessary object creation, and redundant function calls to improve performance. This is especially critical in memory-sensitive areas and frequently executed code paths.

Key practices:
- Cache expensive computation results instead of recalculating them
- Reuse existing objects/arrays rather than creating new ones when possible  
- Avoid calling the same function multiple times with identical parameters
- Profile code to identify performance bottlenecks from redundant work

Example from codebase:
```typescript
// Before: Redundant calls
const isVisible1 = isElementVisible(element);
const isVisible2 = isElementVisible(element); // Same element, duplicate call

// After: Cache the result
const isVisible = isElementVisible(element);
// Use 'isVisible' variable in both places

// Before: Creating new array
return annotations.map(annotation => ({ ...annotation, location: absolutePath }));

// After: Modify in place when safe
annotations.forEach(annotation => annotation.location = absolutePath);
return annotations;
```

This optimization becomes increasingly important in hot code paths, loops, and memory-constrained environments where even small inefficiencies can compound into significant performance impacts.

---

## Format for readability

<!-- source: ghostty-org/ghostty | topic: Documentation | language: Markdown | updated: 2025-07-04 -->

Documentation should be formatted to optimize readability and information retention. Apply these principles to make documentation more user-friendly:

1. Place explanatory text close to related code examples, avoiding isolated sentences that break the flow of information.

2. Use text formatting (especially **bold**) to highlight key terms and important concepts that readers might need when skimming the document.

3. Structure information logically, with explanations preceding code examples when they provide context for understanding the example.

Example of good formatting:

```markdown
Add a line to the CODEOWNERS file (where `xx_YY` is your locale):

```diff
 # Localization
 /po/README_TRANSLATORS.md @ghostty-org/localization
 /po/com.mitchellh.ghostty.pot @ghostty-org/localization
 /po/zh_CN.UTF-8.po @ghostty-org/zh_CN
+/po/xx_YY.UTF-8.po @ghostty-org/xx_YY
```
```

This standard helps documentation serve both careful readers and those quickly scanning for specific information.

---

## API extensibility parameters

<!-- source: neovim/neovim | topic: API | language: C | updated: 2025-07-04 -->

Always design API functions with extensible parameter structures to accommodate future feature expansion without breaking changes. Use `Dict opts` parameters instead of individual boolean or primitive parameters, unless you are absolutely certain no expansion will ever be needed (which is usually wrong).

This approach prevents the need for API versioning or breaking changes when new functionality is added. Even if the initial implementation doesn't use all possible options, the extensible structure allows for seamless feature additions.

Example of preferred API design:
```c
// Good: Extensible with opts parameter
Tabpage nvim_open_tabpage(Buffer buffer, Boolean enter, Dict opts, Error *err)

// Avoid: Fixed parameters that may need expansion later  
Tabpage nvim_open_tabpage(Buffer buffer, Boolean enter, Error *err)
```

The `opts` dictionary can initially be empty or contain basic options, but provides a clear path for adding features like positioning (`after` parameter mirroring `[count]tabnew`), styling options, or behavioral flags without requiring new API endpoints or breaking existing client code.

This principle applies even when the API seems simple initially - consider future use cases like custom commands (`:restart +qall`) or additional configuration options that users might request.

---

## Proper documentation linking

<!-- source: zed-industries/zed | topic: Documentation | language: Markdown | updated: 2025-07-04 -->

Documentation should use appropriate linking strategies to ensure content remains accessible and navigable across all deployment environments:

1. **Use absolute URLs for repository links**: When referencing files within the codebase (like READMEs or source files), always use absolute GitHub URLs instead of relative paths that may break when documentation is deployed to external sites.

   ```markdown
   <!-- Incorrect -->
   Follow the steps in the [collab README](../../../crates/collab/README.md)

   <!-- Correct -->
   Follow the steps in the [collab README](https://github.com/organization/repo/blob/main/crates/collab/README.md)
   ```

2. **Implement cross-references between related documentation**: When functionality is documented across multiple locations, add cross-references to help users find all relevant information. This is particularly important for features that have both configuration and usage instructions in different sections.

3. **Test links in the deployed environment**: Verify that all documentation links work correctly not just in the source repository, but also in the final deployed documentation site.

Following these practices ensures documentation remains navigable and useful regardless of where or how users access it.

---

## Secure temporary files

<!-- source: ghostty-org/ghostty | topic: Security | language: Other | updated: 2025-07-04 -->

Always use `mktemp` instead of manually constructing temporary file paths with random values. Manually constructed paths with elements like `$RANDOM` or timestamp values can be vulnerable to race conditions, predictability issues, and permission problems, potentially leading to security exploits.

**Instead of:**
```bash
cpath="/tmp/ghostty-ssh-$USER-$RANDOM-$(date +%s)"
```

**Use:**
```bash
cpath=$(mktemp -d /tmp/ghostty-ssh-XXXXXX)
# or for a file
cpath=$(mktemp /tmp/ghostty-ssh-XXXXXX)
```

The `mktemp` utility creates unique temporary files/directories safely, sets appropriate permissions, and handles race conditions properly. This prevents potential security vulnerabilities like file-based race conditions, symbolic link attacks, and information disclosure that could occur with manually constructed paths.

---

## Handle nulls with Option

<!-- source: astral-sh/ruff | topic: Null Handling | language: Rust | updated: 2025-07-03 -->

Use Rust's Option type and its methods effectively to handle nullable values. This improves code clarity and safety by making null cases explicit and leveraging the type system.

Key practices:
1. Prefer Option<T> over tuple/primitive returns for nullable values
2. Use appropriate Option methods:
   - unwrap_or_default() for default values
   - expect() with descriptive messages for cases that shouldn't be null
   - is_some_and() for conditional checks
3. Remove redundant null checks when Option already provides the safety

Example - Before:
```rust
// Using tuple return
fn is_pragma_comment(comment: &str) -> (bool, usize) {
    // Returns (is_pragma, offset)
    if comment.contains("pragma") {
        (true, comment.find("pragma").unwrap_or(0))
    } else {
        (false, 0)
    }
}
```

After:
```rust
// Using Option for clearer semantics
fn is_pragma_comment(comment: &str) -> Option<usize> {
    // Returns offset if comment is pragma, None otherwise
    comment.contains("pragma").then(|| {
        comment.find("pragma").expect("pragma exists")
    })
}

// Usage with appropriate Option methods
let offset = is_pragma_comment(comment)
    .unwrap_or_default();  // Use default when None
```

This approach:
- Makes null cases explicit in the type system
- Reduces error-prone manual null checking
- Provides clear, chainable operations for handling null cases
- Improves code readability and maintainability

---

## API parameter clarity

<!-- source: microsoft/playwright | topic: API | language: TypeScript | updated: 2025-07-03 -->

Design API parameters to be self-documenting and minimize cognitive overhead. Avoid boolean parameters in favor of descriptive enums or string literals, leverage type inference where possible, and prefer clean parameter passing over state mutation patterns.

Key principles:
- Replace boolean flags with descriptive string literals or enums that clearly indicate behavior
- Implement automatic type/parameter inference when context provides sufficient information
- Pass new values as parameters rather than mutating state and rolling back on failure
- Remove redundant parameters when all callers use the same value

Example of boolean parameter improvement:
```typescript
// Instead of:
async function processSnapshot(updateIndex: boolean) {
  // unclear what true/false means
}

// Use descriptive options:
async function processSnapshot(indexBehavior: 'updateAnonymousSnapshotIndex' | 'dontUpdateAnonymousSnapshotIndex') {
  // behavior is immediately clear
}
```

Example of parameter inference:
```typescript
// Instead of requiring explicit contentType:
await testInfo.attach('report.html', { 
  path: attachmentFile, 
  contentType: 'text/html' // redundant
});

// Infer from file extension:
await testInfo.attach('report.html', { 
  path: attachmentFile // contentType inferred from .html extension
});
```

This approach reduces API surface area, prevents misuse, and makes code more maintainable by encoding intent directly in the parameter names and types.

---

## Consider algorithmic complexity tradeoffs

<!-- source: astral-sh/ruff | topic: Algorithms | language: Rust | updated: 2025-07-03 -->

When implementing algorithms or data structures, carefully evaluate the tradeoffs between computational complexity, memory usage, and code maintainability. Consider:

1. Time complexity implications of operations
2. Memory overhead of data structures
3. Impact on code maintainability
4. Whether optimizations are justified by real-world usage patterns

For example, when choosing between different implementations:

```rust
// Less efficient but simpler and more maintainable
match to_remove[..] {
    [] => self.elements.push(to_add),
    [index] => self.elements[index] = to_add,
    _ => {
        // Simple but potentially slower approach
        for index in to_remove.into_iter().rev() {
            self.elements.swap_remove(index);
        }
        self.elements.push(to_add);
    }
}

// More efficient but harder to understand
if let Some((&first, rest)) = to_remove.split_first() {
    self.elements[first] = to_add;
    // Complex optimization logic...
}
```

Choose the simpler implementation unless profiling shows that the optimization provides meaningful benefits for your use case. Document the rationale for choosing more complex implementations when necessary.

---

## Document component behavior comprehensively

<!-- source: astral-sh/ruff | topic: Documentation | language: Rust | updated: 2025-07-03 -->

Documentation should clearly explain the purpose, behavior, and relationships between code components using accessible terminology. This helps other developers understand the code without needing to dig into implementations.

Key practices:
1. Document relationships between components (classes, traits, modules) to show how they interact
2. Explain the purpose of fields in data structures and enums
3. Document function behavior limitations, edge cases, and potential failure modes
4. Use terminology accessible to users without deep implementation knowledge

Example of improved documentation:

```rust
/// A tuple length specification.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) enum TupleLength {
    /// A tuple with exactly `n` elements
    Fixed(usize),
    /// A variable-length tuple with `prefix_len` required elements at the start
    /// and `suffix_len` required elements at the end
    Variable(usize, usize),
}

/// Return true if this is a type that is always fully static (has no dynamic part; 
/// represents a single set of possible values.)
///
/// Note: This function may have false negatives (return false for some static types),
/// but should not have false positives (will never return true for non-static types).
fn is_fully_static(&self) -> bool {
    // implementation...
}
```

When documenting methods that may panic or fail under certain conditions, clearly state these conditions:

```rust
/// Get the AST node for this class.
/// 
/// # Panics
/// Panics if the provided module belongs to a different file than this class.
fn node<'ast>(self, db: &'db dyn Db, module: &'ast ParsedModuleRef) -> &'ast ast::StmtClassDef {
    // implementation...
}
```

Comprehensive documentation reduces the learning curve for new contributors and helps prevent bugs caused by misunderstandings about component behavior.

---

## Profile allocations before optimization

<!-- source: astral-sh/ruff | topic: Performance Optimization | language: Rust | updated: 2025-07-03 -->

Before implementing data structures or algorithms, analyze allocation patterns and optimize for common cases. Key strategies:

1. Use fixed-size arrays for known small collections:
```rust
// Before
pub fn all() -> Vec<&'static str> {
    vec!["namespace", "class", ...]
}

// After
pub const fn all() -> [&'static str; 15] {
    ["namespace", "class", ...]
}
```

2. Leverage specialized data structures to avoid allocations:
- Use `hashbrown::HashMap` with `entry_ref` for string keys
- Consider `smallvec` for collections that are usually small
- Keep allocations behind `Arc` when possible

3. Profile before optimizing:
- Measure binary size impact of changes
- Use tools like cargo-bloat to identify hot spots
- Consider both debug and release mode implications

The goal is to minimize allocations in hot paths while keeping code maintainable. Always validate optimizations with benchmarks and profiles.

---

## Optimize CI/CD commands

<!-- source: astral-sh/uv | topic: CI/CD | language: Yaml | updated: 2025-07-03 -->

{% raw %}
Design CI/CD workflows to be efficient, consistent, and purposeful across all environments. When writing or modifying pipeline scripts:

1. Batch related operations to minimize redundant commands and improve performance
2. Apply security practices consistently across all deployment targets
3. Make intentional choices about caching strategies based on the pipeline's purpose
4. Document the reasoning behind non-obvious configuration decisions

For example, when working with Docker images, prefer batched operations:

```bash
# Inefficient: Multiple separate registry operations
for tag in $TAGS; do
  docker buildx imagetools create -t "${tag}" "${image}@${DIGEST}"
done

# Efficient: Batched operations per registry
readarray -t lines < <(grep "^${image}:" <<< "$TAGS"); tags=(); 
for line in "${lines[@]}"; do tags+=(-t "$line"); done
docker buildx imagetools create "${tags[@]}" "${image}@${DIGEST}"
```

For build caching strategies, be intentional about clean vs. incremental builds:

```yaml
# Explicitly using source files in cache key to ensure clean builds in release pipelines
- name: Docker Cargo caches
  uses: actions/cache@v4
  with:
    key: docker-cargo-caches-${{ matrix.platform }}-${{ hashFiles('Dockerfile', 'crates/**', 'Cargo.toml', 'Cargo.lock') }}
```
{% endraw %}

---

## Choose domain-specific semantic names

<!-- source: zed-industries/zed | topic: Naming Conventions | language: Rust | updated: 2025-07-03 -->

Names should clearly reflect their domain-specific meaning and purpose, avoiding generic or ambiguous terms. This applies to variables, methods, classes, and other identifiers. When naming, consider:

1. Use domain terminology that precisely describes the concept
2. Avoid broad or generic terms that could be ambiguous in the codebase context
3. Be explicit about the purpose or behavior
4. Maintain consistency with established domain naming patterns

Example:
```rust
// Avoid: Generic or ambiguous names
pub fn tokens(&self) -> &Arc<SemanticTheme> { ... }
let askpass_content = format!(...);

// Better: Domain-specific semantic names
pub fn semantic_tokens(&self) -> &Arc<SemanticTheme> { ... }
let askpass_script = format!(...);
```

This approach helps maintain clarity and reduces confusion, especially in large codebases where context may not be immediately apparent. When introducing new names, ensure they align with the domain language used throughout the project.

---

## Leverage existing API utilities

<!-- source: astral-sh/ruff | topic: API | language: Rust | updated: 2025-07-03 -->

When implementing or consuming APIs, always prefer using existing utility methods and abstractions over manual implementations. This reduces code duplication, improves consistency, and helps avoid subtle bugs in conversion logic or interface handling.

For example, when working with text ranges in a language server:

```rust
// Instead of this manual conversion:
let start_offset = params.range.start.to_text_size(&source, &line_index, snapshot.encoding());
let end_offset = params.range.end.to_text_size(&source, &line_index, snapshot.encoding());
let requested_range = ruff_text_size::TextRange::new(start_offset, end_offset);

// Use the existing utility method:
let requested_range = params.range.to_text_range(...);
```

Similarly, when checking module types or other special cases:

```rust
// Instead of string comparison:
builtin: module_name.as_str() == "builtins"

// Use the domain-specific API:
builtin: module.is_known(KnownModule::Builtins)
```

And when performing pattern matching on expressions:

```rust
// Instead of nested match statements:
match expr {
    Expr::Call(expr_call) => match checker.semantic().resolve_qualified_name(&expr_call.func) {
        Some(name) => name.segments() == ["pathlib", "Path"],
        None => false,
    },
    _ => false,
}

// Use method chaining with is_some_and:
expr.as_call_expr().is_some_and(|expr_call| {
    checker
        .semantic()
        .resolve_qualified_name(&expr_call.func)
        .is_some_and(|name| matches!(name.segments(), ["pathlib", "Path"]))
})
```

Take time to familiarize yourself with the available utilities in the API you're working with, particularly for common operations like conversions, validations, and pattern matching.

---

## Maintain focused module structure

<!-- source: astral-sh/ruff | topic: Code Style | language: Rust | updated: 2025-07-03 -->

Keep modules focused and well-organized by grouping related functionality together and splitting large files into logical submodules. Each file should have a clear, single responsibility. When a file grows too large or handles multiple concerns, consider breaking it into smaller, more focused modules.

For example, instead of:
```rust
// types.rs (large file with mixed concerns)
pub(crate) trait VarianceInferable<'db>: Sized {
    // ... variance-related code
}

pub(crate) struct TypeVarInstance<'db> {
    // ... type variable code
}
```

Prefer:
```rust
// types/variance.rs
pub(crate) trait VarianceInferable<'db>: Sized {
    // ... variance-related code
}

// types/type_var.rs
pub(crate) struct TypeVarInstance<'db> {
    // ... type variable code
}
```

Key guidelines:
- Keep files focused on a single responsibility or closely related set of functionality
- Use submodules to organize related code (e.g., types/variance.rs, types/type_var.rs)
- Consider splitting a file when it becomes difficult to navigate or understand as a whole
- Group related functionality together in the same module
- Use clear module names that reflect their contents

---

## Contextualize don't panic

<!-- source: zed-industries/zed | topic: Error Handling | language: Rust | updated: 2025-07-03 -->

Always provide meaningful context for errors and avoid code that can panic in production. Use `.context()` or `.with_context()` to add rich error information, making debugging easier. Replace `.unwrap()` and `.expect()` with proper error handling mechanisms like error propagation or logging.

Example - Poor error handling:
```rust
// No context added to errors
fs::write(&askpass_script_path, askpass_script).await?;

// Potential panics in production
let file_path = python_extract_path_and_line(file_line.as_str())
    .expect("Cannot parse python file line syntax");
```

Example - Better error handling:
```rust
// Rich context added to errors
fs::write(&askpass_script_path, askpass_script)
    .await
    .with_context(|| format!("Creating askpass script at {askpass_script_path:?}"))?;

// No panic risk, proper error propagation
let file_path = match python_extract_path_and_line(file_line.as_str()) {
    Some(result) => result,
    None => {
        log::warn!("Failed to parse Python file line syntax: {}", file_line);
        return None;
    }
};
```

For error handling in library code, preserve full error information rather than simplifying too early (e.g., prefer returning `Result` over `Option` when information might be useful). When handling errors that shouldn't propagate, use `.log_err()` rather than silently discarding them with `let _`.

---

## Assert exact expectations

<!-- source: astral-sh/ruff | topic: Testing | language: Rust | updated: 2025-07-03 -->

Always assert exact expected values in tests rather than using loose assertions. When testing the presence of elements or count of items, use equality assertions (`assert_eq!`) instead of non-empty checks (`assert!(!items.is_empty())`) or inequality assertions (`assert!(items.len() >= 2)`).

Exact assertions:
- Make test failures more informative by showing the expected and actual values
- Prevent silent test degradation when code changes affect output quantity
- Catch unexpected behavior that looser assertions would miss

For example, instead of:

```rust
// Testing that some tokens exist (too loose)
let class_tokens = tokens.iter()
    .filter(|t| matches!(t.token_type, SemanticTokenType::Class))
    .collect();
assert!(!class_tokens.is_empty());

// Using inequality (can hide issues)
let variable_tokens = tokens.iter()
    .filter(|t| matches!(t.token_type, SemanticTokenType::Variable))
    .collect();
assert!(variable_tokens.len() >= 2);
```

Use this approach instead:

```rust
// Test for the exact expected count
let class_tokens = tokens.iter()
    .filter(|t| matches!(t.token_type, SemanticTokenType::Class))
    .collect();
assert_eq!(class_tokens.len(), 1);

// Or use a helper function for multiple assertions
assert_token_count([
    (SemanticTokenType::BuiltinConstant, 3),
    (SemanticTokenType::Variable, 3),
]);
```

When practical, consider extracting assertions into helper functions that verify the exact composition of test results, making tests more readable and consistent.

---

## Structure documentation effectively

<!-- source: astral-sh/ruff | topic: Documentation | language: Markdown | updated: 2025-07-03 -->

Documentation should follow a consistent structure where explanations precede code examples, preferably ending with a colon to introduce the code. When documenting special cases or complex behaviors, include links to relevant external specifications or standards. Consolidate similar documentation to avoid duplication across files.

Example:
```md
## The `nonlocal` keyword

Without the `nonlocal` keyword, `x += 1` (or `x = x + 1` or `x = foo(x)`) is not allowed in an inner
scope like this. It might look like it would read the outer `x` and write to the inner `x`, but it
actually tries to read the not-yet-initialized inner `x` and raises `UnboundLocalError` at runtime:

```py
def f():
    x = 1
    def g():
        x += 1  # error: [unresolved-reference]
```

See [Python language reference](https://docs.python.org/3/reference/simple_stmts.html#the-nonlocal-statement) for more details.
```

---

## Minimize credential exposure lifetime

<!-- source: zed-industries/zed | topic: Security | language: Rust | updated: 2025-07-03 -->

Credentials and secrets should never be stored persistently in memory or written to files. Instead, use ephemeral patterns that limit the lifetime of sensitive data:

1. Use one-time channels or receivers to pass credentials only when needed
2. Immediately consume credentials rather than storing them in struct fields
3. Ensure sensitive data is properly cleared/dropped after use

Example of a problematic pattern:
```rust
pub struct AskPassSession {
    askpass_helper: String,
    _askpass_task: Task<()>,
    secret: std::sync::Arc<std::sync::Mutex<String>>, // Stores credential persistently
}
```

Better pattern:
```rust
// Create a one-time channel for the credential
let (askpass, askpass_rx) = create_oneshot_channel();

// Use the credential only when needed
let Some(password) = askpass_rx.next().await else { /* handle error */ };
let socket = SshSocket::new(connection_options, &temp_dir, password)?;

// Password is consumed and doesn't persist in memory
```

This approach ensures credentials exist in memory only for the minimum time necessary and reduces the security risk if the application memory is compromised.

---

## Structure for readability

<!-- source: astral-sh/uv | topic: Code Style | language: Rust | updated: 2025-07-02 -->

Organize code to maximize readability and maintainability. When code becomes complex, break it down into smaller, more manageable pieces with clear responsibilities:

1. **Place initialization logic in constructors**: Ensure objects are always in a valid state by initializing them fully in constructors rather than requiring separate initialization methods.

```rust
// Instead of:
struct FilesystemLocks {
    root: PathBuf,
}

impl FilesystemLocks {
    fn from_path(root: impl Into<PathBuf>) -> Self {
        Self { root: root.into() }
    }
    
    fn init(self) -> Result<Self, std::io::Error> {
        // Initialize here...
    }
}

// Prefer:
struct FilesystemLocks {
    root: PathBuf,
}

impl FilesystemLocks {
    fn from_path(root: impl Into<PathBuf>) -> Result<Self, std::io::Error> {
        let this = Self { root: root.into() };
        // Initialize here...
        Ok(this)
    }
}
```

2. **Extract complex expressions**: Assign complex expressions to named variables outside of nested structures to clarify their purpose and make code flow easier to follow.

3. **Create dedicated types**: When functionality around a concept grows complex, consider creating a dedicated type to encapsulate that logic and provide a cleaner interface.

4. **Combine related implementations**: Keep related functionality together by avoiding multiple separate `impl` blocks for the same type when they're logically connected.

Following these principles leads to code that is easier to understand, maintain, and extend.

---

## Explicit null handling

<!-- source: bazelbuild/bazel | topic: Null Handling | language: Java | updated: 2025-07-02 -->

Always make null handling explicit through proper annotations, defensive checks, and clear documentation. Use @Nullable annotations for parameters and fields that can be null, add precondition checks with meaningful error messages for required non-null values, and document when and why values may be null.

For nullable parameters and fields, use @Nullable annotations with explanatory comments:
```java
@Nullable
private final String mnemonic; // null if not yet known

public void maybeReportSubcommand(Spawn spawn, @Nullable String spawnRunner) {
  // method implementation
}
```

For required non-null parameters, use defensive precondition checks that include the problematic value in error messages:
```java
public ExecutionInfo(Map<String, String> requirements, String execGroup) {
  this.executionInfo = ImmutableMap.copyOf(requirements);
  this.execGroup = checkNotNull(execGroup, "execGroup cannot be null");
}

// Pass the input to checkNotNull for better error context
FileArtifactValue metadata = checkNotNull(metadataSupplier.getMetadata(input), input);
```

Document null behavior in javadoc, especially for return values:
```java
/**
 * Returns the action result from cache.
 * @return the cached result, or null if not found in cache
 */
@Nullable
public abstract ActionResult actionResult();
```

This approach prevents null-related bugs by making null contracts explicit and providing clear failure points when null constraints are violated.

---

## build action separation

<!-- source: bazelbuild/bazel | topic: CI/CD | language: Java | updated: 2025-07-02 -->

Keep build actions focused on their core responsibility and move complex logic to appropriate abstraction layers like builders or configuration components. Build actions should contain minimal action-specific branching and avoid tight coupling to implementation details.

This principle improves build system maintainability and reliability in CI/CD pipelines by:
- Making actions easier to debug when builds fail
- Reducing complexity that can lead to unpredictable behavior
- Enabling better separation of concerns for different build phases
- Avoiding architectural decisions that make the system harder to extend

For example, instead of adding conditional logic directly in a compile action:

```java
// Avoid: Complex branching in action
if (featureConfiguration.isEnabled(CppRuleClasses.CPP_MODULES)) {
  if (dotdFile != null) {
    outputs.add(dotdFile);
  }
}
```

Move the logic to the builder where it belongs:

```java
// Prefer: Logic in builder, clean action
// Builder handles the conditional logic
// Action just processes what builder provides
```

Similarly, avoid introducing special artifacts or complex coupling that makes the build system "un-Starlarkifiable" or harder to maintain. When build actions stay focused and delegate complex decisions to appropriate layers, the entire CI/CD pipeline becomes more reliable and easier to troubleshoot.

---

## Clarify testing documentation

<!-- source: cypress-io/cypress | topic: Testing | language: Markdown | updated: 2025-07-02 -->

Ensure that testing documentation, including changelogs, API docs, and guides, uses clear and precise language that doesn't confuse developers. Avoid ambiguous statements that might mislead users who already understand the concepts, use proper technical terminology, and provide concrete examples that reflect real-world usage patterns.

For example, when documenting testing behavior changes:
- Instead of: "assertions are now fully retryable" (when they already were)
- Use: "assertions now retry consistently in all contexts, including when chained with DOM commands"

When writing testing guides:
- Recommend building wrapper components "that will be close to how your users will use this component"
- Provide specific examples of realistic test scenarios

Always verify technical terms are properly capitalized (e.g., "WebKit" not "Webkit") and that explanations help rather than confuse the intended audience.

---

## Validate configurations comprehensively

<!-- source: vercel/turborepo | topic: Configurations | language: Rust | updated: 2025-07-01 -->

When implementing configuration systems, ensure comprehensive validation, testing, and documentation. Key requirements:

1. Use an allowlist approach - explicitly categorize and validate ALL configuration fields
2. Test both serialization and deserialization of configuration
3. Document validation rules and error messages clearly
4. Handle environment variable overrides systematically

Example:
```rust
#[derive(Serialize, Deserialize, Debug)]
pub struct Config {
    // Explicitly document field purpose
    /// Controls daemon behavior, defaults to false in CI
    pub daemon: Option<bool>,
    
    // Add validation methods
    pub fn validate(&self) -> Result<(), Error> {
        // Explicit validation logic
    }
}

#[cfg(test)]
mod tests {
    #[test]
    fn test_config_serialization() {
        // Test both serialization and deserialization
        let json = r#"{ "daemon": true }"#;
        let config: Config = serde_json::from_str(json).unwrap();
        assert_eq!(config.daemon, Some(true));
        
        let serialized = serde_json::to_string(&config).unwrap();
        assert_eq!(serialized, json);
    }
}

---

## Optimize collection operations

<!-- source: Homebrew/brew | topic: Algorithms | language: Ruby | updated: 2025-07-01 -->

Use Ruby's built-in collection methods to write more efficient and readable code. This reduces algorithmic complexity and improves performance by leveraging optimized implementations instead of writing manual iterations or chaining multiple operations.

Specifically:

1. Use destructive methods with exclamation points when modifying collections in-place:
```ruby
# Instead of:
upgradeable = upgradeable.reject { |f| FormulaInstaller.installed.to_a.include?(f) }

# Prefer:
upgradeable.reject! { |f| FormulaInstaller.installed.include?(f) }
```

2. Use array operations and splats for manipulation instead of multiple method calls:
```ruby
# Instead of:
json["old_tokens"] = (json["old_tokens"] << old_token).uniq

# Prefer:
json["old_tokens"] = [old_token, *json["old_tokens"]].compact.uniq
```

3. Use Symbol#to_proc syntax with methods like `map` and `filter_map` to create more concise code:
```ruby
# Instead of:
installed_formula_tap_names = Formula.installed.map { |f| f.tap.name }
                                    .reject { |name| name == "homebrew/core" }.uniq

# Prefer:
installed_formula_tap_names = Formula.installed.filter_map(&:tap).uniq.reject(&:official?)
```

4. Consider memoization for expensive operations that may be called repeatedly:
```ruby
# Instead of:
def non_core_taps
  Tap.installed.reject(&:core_tap?).reject(&:core_cask_tap?)
end

# Prefer:
def non_core_taps
  @non_core_taps ||= Tap.installed.reject(&:core_tap?).reject(&:core_cask_tap?)
end
```

These approaches lead to faster algorithms, reduced memory usage, and more maintainable code.

---

## Test through public APIs

<!-- source: zed-industries/zed | topic: Testing | language: Rust | updated: 2025-07-01 -->

Write comprehensive tests that validate functionality through public interfaces rather than testing implementation details. Tests should cover diverse scenarios, handle platform-specific cases, and use appropriate assertions.

Key principles:
1. Test public contracts instead of private methods
2. Include diverse test cases (e.g., multibyte characters, edge cases)
3. Use platform-specific configurations when needed
4. Prefer visual/structural assertions over numeric ones

Example:

```rust
// Instead of testing private implementation:
#[test]
fn test_valid_url_ending() {
    assert!(valid_url_ending("http://example.com"));
}

// Better - test through public API with comprehensive cases:
#[test]
fn test_url_regex() {
    let urls = [
        "http://example.com",
        "http://example.com/(test)",
        "http://ünicode.com",
        "[http://example.com]"
    ];
    
    for url in urls {
        let matches = find_urls(url);
        assert_eq!(matches[0], url.trim_matches(|c| c == '[' || c == ']'));
    }
}

// Handle platform-specific cases:
#[cfg_attr(target_os = "windows", ignore)]
#[test]
fn test_file_operations() {
    // Platform-specific test implementation
}
```

---

## Consider algorithmic complexity

<!-- source: zed-industries/zed | topic: Algorithms | language: Rust | updated: 2025-07-01 -->

When implementing algorithms, be mindful of their computational complexity and choose appropriate data structures for operations. 

1. **Use specialized collections for their strengths**:
   - For deduplication, prefer `HashSet` over repeatedly checking `Vec.contains()`.
   - Consider specialized libraries like `Itertools` for common operations.
   - Choose data structures based on access patterns:
     ```rust
     // Instead of:
     let mut models = BTreeMap::default();  // Causes unwanted sorting
     
     // Use:
     let mut models = Vec::new();  // Preserves insertion order when sorting isn't needed
     ```

2. **Avoid quadratic complexity**:
   - Watch for hidden O(N²) operations, especially nested loops over the same data:
     ```rust
     // Inefficient O(N²) - iterating outlines twice:
     for outline in fetched_outlines {
         // ... then for each outline we iterate again
         if outline_panel.has_outline_children(&outline_entry, cx) {
             // ...
         }
     }
     
     // Better: Process in a single pass with appropriate data structures
     ```

3. **Eliminate unnecessary operations**:
   - Avoid creating intermediate allocations when passing predicates or filters:
     ```rust
     // Inefficient - unnecessarily clones data:
     tasks.retain_mut(|(task_source_kind, target_task)| {
         predicate(&(task_source_kind.clone(), target_task.clone()))
     });
     
     // Better - uses references:
     tasks.retain_mut(|(task_source_kind, target_task)| {
         predicate(&(task_source_kind, target_task))
     });
     ```
   
4. **Use functional patterns for string operations**:
   - Replace imperative loops with more expressive functional alternatives:
     ```rust
     // Instead of manual character loop:
     let mut common_prefix_len = 0;
     for (a, b) in old_text.chars().zip(new_text.chars()) {
         if a == b {
             common_prefix_len += a.len_utf8();
         } else {
             break;
         }
     }
     
     // More expressive functional approach:
     let common_prefix_len = old_text
         .chars()
         .zip(new_text.chars())
         .take_while(|(a, b)| a == b)
         .map(|(a, _)| a.len_utf8())
         .sum::<usize>();
     ```

By consistently applying these principles, you'll create more efficient, maintainable code that performs well even as input sizes grow.

---

## Use descriptive identifiers

<!-- source: astral-sh/ruff | topic: Naming Conventions | language: Rust | updated: 2025-07-01 -->

Avoid abbreviations in variable, parameter, and method names to improve code readability and maintainability. Use descriptive identifiers that clearly indicate the purpose and content of what they represent.

Instead of:
```rust
// Abbreviated variable names
let spec = self.specialization;
let ctx = self.generic_context;
let ty = self.inferred_return_type();
let tvar = TypeVar(...);
```

Prefer:
```rust
// Descriptive variable names
let specialization = self.specialization;
let generic_context = self.generic_context;
let return_type = self.inferred_return_type();
let type_var = TypeVar(...);
```

Additionally:
- Functions should use verb phrases: use `infer_return_type()` not `inferred_return_ty()`
- Use meaningful variable names that match what they represent: if a variable holds a place expression, name it `place_expr` not just `expr`
- For generated/synthetic names (like type variables), use distinctive names that won't conflict with common user code: use `T_all` instead of just `T`
- Choose names that reflect the semantic meaning of the data, not just its type

Descriptive names make code easier to understand at first glance and reduce the cognitive load required to comprehend complex logic.

---

## Protect render loop performance

<!-- source: zed-industries/zed | topic: Performance Optimization | language: Rust | updated: 2025-07-01 -->

Ensure render loop operations stay within frame time budget (typically 16.67ms for 60fps). Avoid expensive computations, traversals, and I/O operations during frame rendering. Instead, compute and cache results ahead of time or move heavy operations to background tasks.

Example of problematic code:
```rust
fn render_outline(&self, cx: &mut Context) {
    // Bad: Expensive loop during rendering
    for outline in self.outlines {
        if self.has_outline_children(outline, cx) {
            // ... rendering logic
        }
    }
}
```

Better approach:
```rust
fn render_outline(&self, cx: &mut Context) {
    // Good: Use pre-computed results during render
    for (outline, has_children) in &self.cached_outline_data {
        if *has_children {
            // ... rendering logic
        }
    }
}

// Update cache in background or on data changes
fn update_outline_cache(&mut self, cx: &mut Context) {
    let mut cached_data = Vec::new();
    for outline in self.outlines {
        cached_data.push((outline, self.has_outline_children(outline, cx)));
    }
    self.cached_outline_data = cached_data;
}
```

Key guidelines:
- Cache computed values that are expensive to calculate
- Move tree traversals, I/O operations, and heavy computations outside the render loop
- Use background tasks for expensive operations that need to update the UI
- Consider debouncing frequent updates to avoid unnecessary recalculations

---

## Validate configuration structures

<!-- source: vercel/turborepo | topic: Configurations | language: TypeScript | updated: 2025-07-01 -->

Ensure configuration files and schemas adhere to their expected structure, location, and uniqueness constraints. When supporting multiple configuration file formats (e.g., both .json and .jsonc extensions), implement validation to prevent conflicting configurations:

```typescript
// Good practice: Check for conflicting config files
function resolveTurboConfigPath(workspacePath: string) {
  const turboJsonPath = path.join(workspacePath, "turbo.json");
  const turboJsoncPath = path.join(workspacePath, "turbo.jsonc");
  
  const turboJsonExists = fs.existsSync(turboJsonPath);
  const turboJsoncExists = fs.existsSync(turboJsoncPath);
  
  if (turboJsonExists && turboJsoncExists) {
    throw new Error(`Found both turbo.json and turbo.jsonc in ${workspacePath}. Please use only one.`);
  }
  
  // Return appropriate config path...
}
```

When defining configuration schemas, ensure properties are placed at their correct hierarchical level and not incorrectly nested. Regularly verify that configuration documentation matches the actual implementation, especially after making changes that affect how users configure your tools.

When users report confusion about configuration usage, prioritize updating documentation and examples to reflect the current expected configuration format.

---

## Declarative constraints over runtime

<!-- source: astral-sh/uv | topic: API | language: Rust | updated: 2025-07-01 -->

Design APIs that enforce constraints through type systems and declarative mechanisms rather than runtime checks. This makes invalid states unrepresentable by design and improves both API usability and reliability.

For example, when designing CLI arguments that shouldn't be used together, prefer declarative constraints:

```rust
// Preferred: Declarative constraint
#[arg(long, conflicts_with = "script")]
pub group: Option<String>

// Avoid: Runtime validation
if let (Some(_), Some(_)) = (group, script) {
    bail!("the argument '--group <GROUP>' cannot be used with '--script <SCRIPT>'")
}
```

Similarly, use appropriate types that enforce validity by construction rather than validation after parsing. This applies to enums for limited options, newtype patterns for validated values, and builder patterns with compile-time validation.

---

## Test deployment edge cases

<!-- source: astral-sh/uv | topic: Testing | language: Python | updated: 2025-07-01 -->

Ensure that code paths handling different deployment environments (installation prefixes, target directories, etc.) have proper test coverage. Without tests for these scenarios, it's difficult to trust that the functionality works correctly across all supported environments.

For example, if your code handles different installation paths like:

```python
def find_binary_path():
    targets = [
        # The scripts directory for the base prefix
        sysconfig.get_path("scripts", vars={"base": sys.base_prefix}),
        # Above the package root, from `pip install --prefix`
        _join(_parents(_module_path(), 4), "bin"),
        # Adjacent to the package root, from `pip install --target`
        _join(_parents(_module_path(), 1), "bin"),
    ]
    # ...
```

You should add tests that verify the function works correctly in each deployment scenario. Consider simulating these environments in your test setup:

1. Create test fixtures that mimic different installation structures
2. Test with platform-specific path patterns when needed (e.g., Windows vs. Unix)
3. Ensure test suites appropriately fail (rather than skip) when environment configuration is missing or incorrect

This reduces the risk of deploying code that only works in the development environment but fails in production scenarios.

---

## conditional feature initialization

<!-- source: electron/electron | topic: Configurations | language: Other | updated: 2025-06-30 -->

Only initialize configuration-dependent features, systems, or resources when the relevant settings, flags, or conditions are actually present or enabled. This prevents unnecessary resource allocation, avoids unwanted side effects like creating default contexts, and improves performance by deferring expensive operations until they're needed.

Key patterns to follow:
- Check for required configuration values before initializing dependent systems
- Use guard conditions to prevent initialization when features are disabled
- Wrap feature-specific code with appropriate build flags
- Defer expensive setup operations until the feature is actually used

Example of proper conditional initialization:
```cpp
// Bad: Always initializes prefs regardless of need
if (auto* browser_context = GetDefaultBrowserContext())
  prefs_ = browser_context->prefs();

// Good: Only initialize when actually needed
if (gin_helper::Dictionary restore_options;
    options.Get(options::kWindowStateRestoreOptions, &restore_options)) {
  // Only get prefs when stateId is present
  restore_options.Get(options::kStateId, &window_state_id_);
  if (!window_state_id_.empty()) {
    prefs_ = GetApplicationPrefs();
  }
}
```

Example with feature flags:
```cpp
// Wrap feature-specific code with build flags
#if BUILDFLAG(ENABLE_ELECTRON_EXTENSIONS)
  if (offscreen_use_shared_texture_) {
    dict.Set("texture", tex);
  }
#endif
```

This approach prevents creating unnecessary contexts, avoids performance overhead, and ensures features are only configured when they will actually be used.

---

## Code structure clarity

<!-- source: ghostty-org/ghostty | topic: Code Style | language: Other | updated: 2025-06-30 -->

Write code with clear structural organization that enhances readability and maintainability. Extract duplicated or complex logic into well-named functions, avoid deeply nested conditionals, and use proper type organization.

When identical code appears in multiple places, extract it to a function:
```zig
// Instead of repeating this code in multiple functions:
const count: usize = @intCast(self.nPages());
for (0..count) |position| {
    const page = self.tab_view.getNthPage(@intCast(position));
    // Complex logic here...
}

// Extract it to a dedicated function:
fn setPageIcons(self: *TabView) void {
    const count: usize = @intCast(self.nPages());
    for (0..count) |position| {
        const page = self.tab_view.getNthPage(@intCast(position));
        // Complex logic here...
    }
}
```

For nested conditionals, prefer block expressions or separate helper functions:
```zig
// Instead of deeply nested conditionals:
if (self.window.config.gtk_tab_icons) {
    if (position < 10) {
        // Logic here
    } else {
        // Other logic
    }
} else {
    // Yet another logic
}

// Use block expressions or early returns:
const icon: ?*gio.Icon = icon: {
    if (!self.window.config.gtk_tab_icons) break :icon null;
    if (position >= 10) break :icon null;
    
    // Logic here
    break :icon result;
};
```

Group related types and enums in a single containing struct for better organization:
```zig
// Instead of:
pub const ColorOperationSource = enum(u16) { /* ... */ };
pub const ColorOperationList = enum(u16) { /* ... */ };
pub const ColorOperationKind = enum(u16) { /* ... */ };

// Use a containing struct:
pub const ColorOperation = struct {
    pub const Source = enum(u16) { /* ... */ };
    pub const List = enum(u16) { /* ... */ };
    pub const Kind = enum(u16) { /* ... */ };
};
```

For public interfaces, consider separating functionality into distinct, purpose-specific functions rather than using boolean flags to modify behavior:
```zig
// Instead of:
pub fn init(self: *Window, app: *App, is_quick_terminal: bool) !void {
    // Complex conditional logic based on is_quick_terminal
}

// Prefer:
pub fn init(self: *Window, app: *App) !void {
    // Common initialization
}

pub fn initQuickTerminal(self: *Window, app: *App) !void {
    // Quick terminal specific initialization
}
```

---

## Consistent authentication patterns

<!-- source: astral-sh/uv | topic: API | language: Markdown | updated: 2025-06-30 -->

Design API authentication mechanisms with consistent patterns, clear documentation, and helpful error messages. When implementing authentication:

1. **Document authentication requirements explicitly**:
   - Specify expected username/token formats and any special cases
   - Explain how authentication failures are handled

2. **Design credentials lookup intelligently**:
   ```python
   # Prefer using the base index URL for credential lookup
   # Instead of:
   credentials = keyring.get_credential(package_url, None)
   
   # Use:
   credentials = keyring.get_credential(index_url, None)
   ```

3. **Provide clear error messages for authentication failures**:
   ```
   If you use `--token "$JFROG_TOKEN"` with JFrog, you will receive a 
   401 Unauthorized error as JFrog requires an empty username but 
   uv passes `__token__` as the username when `--token` is used.
   ```

4. **Consider consistency across similar operations**:
   - Use the same authentication patterns for related endpoints
   - Document when different operations require different authentication formats
   - Be explicit about URL formatting requirements (e.g., trailing slashes)

5. **Test authentication edge cases**:
   - Verify behavior with missing credentials
   - Test various token formats
   - Confirm proper handling of authentication failures

---

## temporary security workarounds

<!-- source: bazelbuild/bazel | topic: Security | language: Java | updated: 2025-06-30 -->

When implementing workarounds for OS-level security restrictions, ensure they are explicitly temporary and include clear plans for proper long-term solutions. Avoid recommending users bypass security features through unofficial methods, and instead guide them toward sanctioned approaches when possible.

Security restrictions evolve over time, and workarounds that function today may break in future system updates. Code should detect the specific security context and implement fallbacks gracefully, while documenting the temporary nature of any bypasses.

Example approach:
```java
// Temporary workaround for Ubuntu 24.04 AppArmor restrictions
// TODO: Remove when proper allowlisting mechanism is available
if (stderr.lines().anyMatch(line -> line.endsWith(": \"mount\": Permission denied"))) {
  try {
    runBinTrue(cmdEnv, linuxSandbox, /* wrapInBusybox= */ true);
    return SupportLevel.SUPPORTED_VIA_BUSYBOX;
  } catch (CommandException e2) {
    // Provide guidance for sanctioned solutions rather than workarounds
    cmdEnv.getReporter().handle(Event.warn(
        "linux-sandbox failed due to security restrictions. " +
        "Consider using sanctioned methods to configure permissions."));
  }
}
```

The goal is to maintain functionality while respecting the intent of security measures and preparing for their proper implementation.

---

## Logical content organization

<!-- source: astral-sh/ruff | topic: Code Style | language: Markdown | updated: 2025-06-28 -->

Organize code and documentation logically based on functionality and dependencies. Place files in directories that reflect their purpose rather than superficial characteristics. Structure documentation so prerequisite concepts appear before concepts that depend on them.

For example:
- Test files should be placed in directories matching their core functionality (e.g., tests for special-cased functions should go in the appropriate special-case directory, not in unrelated directories)
- Documentation sections should be ordered so that foundational concepts are introduced first, especially when other sections build upon them (e.g., putting the "Callable" section before "Tuple" when callable arguments are used to demonstrate contravariant contexts)

This organizational approach improves readability, makes the codebase more intuitive to navigate, and helps developers understand relationships between different components.

---

## Choose error strategies deliberately

<!-- source: astral-sh/ruff | topic: Error Handling | language: Rust | updated: 2025-06-27 -->

Make deliberate choices about error handling strategies based on the context. Decide between early returns with appropriate error reporting, panic mechanisms, or silent failures with diagnostics:

1. **Early returns** for expected error conditions:
   ```rust
   // Prefer this when the error is expected in normal operation
   if !output.status.success() {
       return Err(anyhow::anyhow!(
           "Git checkout failed: {}",
           String::from_utf8_lossy(&output.stderr)
       ));
   }
   ```

2. **Panic** only for true invariant violations:
   ```rust
   // Use panic! over unreachable! when an invariant is violated
   match definition.scope(db).node(db) {
       NodeWithScopeKind::Class(_) => {
           panic!("invalid definition kind for type variable")
       }
       // Valid cases...
   }
   ```

3. **Silent failures with diagnostics** when appropriate:
   ```rust
   // Return a sensible default and let type checking handle the error
   if !is_callable(test_expr) {
       return Truthiness::AlwaysFalse;
   }
   ```

Always document functions that can panic and under what conditions. When handling results, be explicit about error propagation choices - consider whether errors should be logged, propagated, or transformed into different error types based on the needs of the caller.

---

## Descriptive consistent naming

<!-- source: vitejs/vite | topic: Naming Conventions | language: TypeScript | updated: 2025-06-27 -->

Choose variable, function, and class names that accurately reflect their purpose while maintaining consistency with established patterns in the codebase. When the purpose or content of an entity changes, update its name accordingly. This applies to:

1. **Function names**: Use general names for general purposes and specific names for specific purposes.
```javascript
// Before: Overly specific name
function getCodeHash(code: string): string { ... }

// After: More general name that matches its versatile purpose
function getHash(input: string): string { ... }
```

2. **Variable names**: Ensure names accurately reflect the actual content.
```javascript
// Before: Misleading name (contains ids, not urls)
const normalizedAcceptedUrls = new Set<string>()

// After: Name matches content
const resolvedAcceptedDeps = new Set<string>()
```

3. **Collection names**: Use plural forms for collections of items.
```javascript
// Before: Singular form for a collection
public fileToModuleMap = new Map<string, ModuleRunnerNode[]>()

// After: Plural form indicating multiple modules
public fileToModulesMap = new Map<string, ModuleRunnerNode[]>()
```

4. **Parameter names**: Choose names that avoid confusion with similar concepts.
```javascript
// Before: Potentially confusing parameter name
function glob(pattern: string, cwd: string): string[] { ... }

// After: More specific name that avoids confusion
function glob(pattern: string, base: string): string[] { ... }
```

5. **Component names**: Follow established naming patterns within the project.
```javascript
// Before: Inconsistent with project naming patterns
{
  name: 'ember app',
  // ...
}

// After: Follows the project's hyphenated naming pattern
{
  name: 'ember-app',
  // ...
}
```

Always prioritize clarity and accuracy in naming to improve code readability and reduce the likelihood of bugs or misunderstandings.

---

## Test edge cases

<!-- source: astral-sh/ruff | topic: Testing | language: Python | updated: 2025-06-27 -->

When writing tests, prioritize coverage of edge cases and non-standard code patterns to ensure robust functionality. Particularly for linting rules or code transformations, identify scenarios that might behave unexpectedly or require special handling.

Include tests for:
- Code with comments in various positions
- Unusual formatting or line continuations
- Nested object constructions
- Dependencies on multiple variables
- Different parameter passing styles (positional vs. keyword)

For example, when testing a rule that transforms string paths to Path objects:

```python
# Test with comments in different positions
func_name( # comment
    "filename")

func_name( # comment
    "filename",
    #comment
)

# Test with line continuations
func_name \
 \
        ( # comment
        "filename",
    )

# Test with nested objects
func_name(Path("filename").resolve())

# Test with dependencies on other variables
for x, y in some_pairs:
    result.add((x, y))
```

Testing these edge cases early prevents subtle bugs from surfacing in production code and makes your code more maintainable over time.

---

## Provide contextual explanations

<!-- source: electron/electron | topic: Documentation | language: Markdown | updated: 2025-06-26 -->

Documentation should explain not just what APIs and features do, but when, why, and how to use them. Provide sufficient context for developers to understand the purpose, appropriate use cases, and practical implementation details.

Key practices:
- Explain the motivation and use cases for features ("Useful for showing splash screens that will be swapped for `WebContentsView`s when the content finishes loading")
- Clarify when features apply or are relevant ("for macOS 12.3 and below—the macOS operating systems which don't support the `ScreenCaptureKit` API")
- Provide complete usage examples that show realistic scenarios
- Explain relationships between related APIs when multiple options exist
- Use clear, unambiguous language that avoids confusion

Example of good contextual documentation:
```js
// Instead of just describing the API
win.webContents.on('paint', (event, dirty, image) => {
  // Handle paint event
})

// Provide context about different usage patterns
const win = new BrowserWindow({ 
  webPreferences: { 
    offscreen: true, 
    offscreenUseSharedTexture: true 
  } 
})

win.webContents.on('paint', async (e, dirty, image) => {
  if (e.texture) {
    // When using shared texture for better performance
    await handleTextureAsync(e.texture.textureInfo)
    e.texture.release() // Important: release when done
  } else {
    // When using traditional bitmap approach
    handleBitmap(image.getBitmap())
  }
})
```

This approach helps developers understand not just the mechanics of an API, but how to use it effectively in real applications.

---

## Design interfaces, not implementations

<!-- source: zed-industries/zed | topic: API | language: Rust | updated: 2025-06-26 -->

Create intuitive API interfaces that abstract away implementation details while providing a consistent experience for consumers. Use appropriate parameter types that express intent and maintain established patterns across your codebase.

When designing function parameters:
- Use enums instead of primitive types for options with discrete values
- Consider builder patterns for complex configurations
- Hide implementation complexity behind clean interfaces
- Extract common patterns into reusable abstractions

```rust
// Before: Implementation-focused API
pub fn fetch(&self, remote_name: String, cx: &mut ModelContext<Self>) { /* ... */ }

// After: Intent-focused API with better parameter types
pub enum FetchTarget {
    AllRemotes,
    SpecificRemote(String)
}

pub fn fetch(&self, target: FetchTarget, cx: &mut ModelContext<Self>) { /* ... */ }

// Before: Platform-specific APIs with inconsistent signatures
fn set_dock_menu(&self, menu: Vec<MenuItem>, keymap: &Keymap) {}
fn update_jump_list(&self, entries: &[&Vec<String>]) -> Option<Vec<Vec<String>>> {}

// After: Unified interface hiding platform differences
fn update_recent_projects(&self, projects: Vec<PathBuf>) -> Result<()> {
    // Platform-specific implementations inside
}

// Maintain consistent builder patterns where established
let branch_button = Button::new("project_branch_trigger", branch_name)
    .color(Color::Muted)
    .style(ButtonStyle::Subtle)
    .when(settings.show_branch_icon, |button| {
        button.with_icon(Icon::GitBranch)
    });
```

Good interfaces reduce coupling between components, improve testability, and create more maintainable systems by allowing implementation details to evolve independently of the API contract.

---

## standardize TODO comments

<!-- source: nrwl/nx | topic: Documentation | language: TypeScript | updated: 2025-06-26 -->

Use version-specific TODO comments with a consistent format to ensure actionable items are properly tracked and easily searchable across the codebase. Include the target version in parentheses immediately after "TODO" to make it clear when the item should be addressed.

This practice helps prevent technical debt from accumulating by making it easy to find and address TODOs during version releases. Without version specificity, TODO comments often become stale and forgotten.

Format TODO comments like this:
```typescript
// TODO(v22): Change default value of useLegacyTypescriptPlugin to false
// TODO(v23): Remove the legacy TypeScript plugin entirely
// TODO(v22) - remove this generator
```

This format enables developers to quickly search for `TODO(v22)` when preparing for version 22 releases, ensuring nothing gets missed during major version updates.

---

## Test all variations

<!-- source: prettier/prettier | topic: Testing | language: Other | updated: 2025-06-26 -->

Ensure comprehensive test coverage by testing all behavioral variations, configuration options, and edge cases rather than just single scenarios. When adding new functionality, preserve existing tests and add new ones to cover both old and new behaviors.

For example, when modifying a function to support both synchronous and asynchronous behavior, maintain separate tests for each:

```javascript
// Keep existing sync test
"foo-parser": {
  preprocess: (text) => `preprocessed:${text}`,

// Add new async test  
"foo-parser-async": {
  preprocess: (text) => Promise.resolve(`preprocessed:${text}`),
```

Similarly, when implementing features with configuration options, test multiple settings rather than just defaults:

```javascript
// Test different quoteProps options
{"quoteProps": "consistent"}
{"quoteProps": "as-needed"} 
{"quoteProps": "preserve"}
```

This approach prevents regressions and ensures robust functionality across all supported use cases.

---

## Avoid unnecessary constraints

<!-- source: astral-sh/uv | topic: Configurations | language: Toml | updated: 2025-06-26 -->

When specifying dependencies and version requirements in project configuration files, avoid adding unnecessary constraints that could limit future compatibility. Unless there's a specific known incompatibility issue:

1. For Python packages in pyproject.toml, specify only the minimum required version rather than adding upper bounds:

```toml
# Preferred
requires-python = ">=3.11"

# Avoid unless necessary
requires-python = ">=3.11,<3.13"
```

2. For library crates in Cargo.toml, be selective about dependencies and consider whether they should be regular or development dependencies. Follow team standards for dependency management:

```toml
# Consider whether dependencies belong in [dependencies] or [dev-dependencies]
# Some dependencies like 'anyhow' should typically be avoided in library crates
```

This practice ensures your configurations remain flexible while still maintaining necessary compatibility requirements.

---

## Prefer idiomatic Option handling

<!-- source: zed-industries/zed | topic: Null Handling | language: Rust | updated: 2025-06-25 -->

When handling null values in Rust, use idiomatic Option patterns instead of verbose nested conditionals. This improves code readability, safety, and reduces the chance of runtime errors.

Always prefer:
1. `is_some_and()` over `map_or(false, |x| ...)` when checking conditions on Option values:
```rust
// Instead of:
self.popover
    .as_ref()
    .map_or(false, |popover| popover.signature.len() > 1)

// Use:
self.popover
    .as_ref()
    .is_some_and(|popover| popover.signature.len() > 1)
```

2. The `?` operator for early returns instead of verbose `if let Some()` patterns:
```rust
// Instead of:
if let Some(editor) = Self::resolve_active_item_as_svg_editor(workspace, cx) {
    if Self::is_svg_file(&editor, cx) {
        // ... implementation ...
    }
}

// Use:
let editor = Self::resolve_active_item_as_svg_editor(workspace, cx)?;
if Self::is_svg_file(&editor, cx) {
    // ... implementation ...
}
```

3. `.ok()` to convert a Result to an Option when appropriate:
```rust
// Instead of:
let system_id = ids::get_or_create_id(&ids::eval_system_id_path())
    .unwrap_or_else(|_| String::new());

// Use:
let system_id = ids::get_or_create_id(&ids::eval_system_id_path()).ok();
```

4. Safe alternatives to `.unwrap()` which can cause runtime panics:
```rust
// Instead of:
workspace.subscribe(&workspace.weak_handle().upgrade().unwrap(), |editor, ...

// Use:
if let Some(workspace) = workspace.weak_handle().upgrade() {
    cx.subscribe(&workspace, |editor, ...
}
```

These patterns make your code more robust against null reference errors while keeping it concise and readable.

---

## Structure user documentation

<!-- source: ghostty-org/ghostty | topic: Documentation | language: Other | updated: 2025-06-25 -->

When documenting complex features or configuration options, structure your documentation with these four key elements:

1. **Concise summary**: Begin with a brief, terse explanation of what the feature does
2. **Problem statement**: Explain what specific user problem this feature solves, focusing on visible consequences to the end user
3. **Technical explanation**: Provide implementation details with appropriate depth
4. **Usage guidance**: Advise when and how users should apply this feature

For example, instead of:

```zig
/// When enabled (any value other than `off`), Ghostty replaces the `ssh` command
/// with a shell function to provide enhanced terminal compatibility and feature
/// propagation when connecting to remote hosts.
```

Prefer this structure:

```zig
///   * `term-only`
///
///     Automatically set the `TERM` environment variable to `xterm-256color` when
///     connecting to remote hosts using SSH.
///
///     By default, Ghostty identifies itself with the terminal type `xterm-ghostty`,
///     which could cause problems for remote machines where Ghostty's _terminfo files_
///     are not installed. Many programs rely on terminfo files to know what the
///     terminal is capable of, and may crash with "unknown terminal type" errors when
///     the terminfo files are absent or exhibit strange behavior.
///
///     When `term-only` is set, for remote connections Ghostty would instead identify
///     itself as `xterm-256color`, which is a compatibility mode understood in most
///     systems.
///
///     This option is best used when you need to connect to a wide variety of remote
///     devices, some of which you might not have access to.
```

Similarly, error messages should be specific and actionable. Instead of vague messages like "your compositor does not support the protocol", provide specific guidance such as "your distro's gtk4-layer-shell version is defective; update to 1.0.4 or later".

---

## prefer managed pointers

<!-- source: hyprwm/Hyprland | topic: Null Handling | language: Other | updated: 2025-06-25 -->

Raw pointers are banned in new code unless absolutely necessary. Instead, use managed pointer types to prevent null pointer dereferences, dangling pointers, and memory safety issues.

Use the appropriate managed pointer type based on ownership semantics:
- `SP<T>` (shared pointer) for shared ownership
- `UP<T>` (unique pointer) for exclusive ownership  
- `WP<T>` (weak pointer) for non-owning references

Example from the codebase:
```cpp
// Bad - raw pointer prone to null dereferences
CExtWorkspaceHandleV1* workspace;
SSessionLockSurface* touchFocusLockSurface;
CXxColorManagementSurfaceV4* m_pCMSurface = nullptr;

// Good - managed pointers prevent null issues
SP<CExtWorkspaceHandleV1> workspace;
WP<SSessionLockSurface> touchFocusLockSurface;  
WP<CXxColorManagementSurfaceV4> m_pCMSurface;
```

For protocol implementations, prefer `UP<>` for resource ownership while allowing `WP<>` references to it. This pattern ensures proper lifetime management and prevents accessing freed memory.

---

## Clear code examples

<!-- source: Homebrew/brew | topic: Documentation | language: Markdown | updated: 2025-06-24 -->

Documentation should include clear, actionable code examples that users can reliably follow. Avoid using ambiguous placeholders or variables that might be misinterpreted as literal code to copy-paste. When placeholder values must be used in examples, explicitly mark them and provide clear instructions for replacement.

For example, instead of:

```sh
eval "${HOMEBREW_PREFIX}/bin/brew shellenv)"
```

Which implies the variable is already set, use one of these approaches:

```sh
# Option 1: Use clear placeholder markers
eval "<Homebrew prefix path>/bin/brew shellenv)"

# Option 2: Include explicit instructions
# Replace /opt/homebrew with your installation directory
eval "/opt/homebrew/bin/brew shellenv)"
```

Similarly, when linking to API methods or classes in documentation, ensure the links are accurate and properly formatted. Check that URLs don't use encoded characters unnecessarily, and test links to confirm they direct to the intended destination.

This practice helps prevent confusion, reduces support requests, and creates a better experience for developers following your documentation.

---

## defensive null checking

<!-- source: electron/electron | topic: Null Handling | language: TypeScript | updated: 2025-06-24 -->

Implement robust null and undefined handling patterns to prevent runtime errors and maintain code reliability. Use optional chaining for safe property access, explicit null checks with early returns, and conditional property assignment to avoid unintended undefined values.

Key patterns to follow:
- Use optional chaining (`?.`) when accessing properties that might be undefined: `if (options?.throwIfNoEntry === true)`
- Add explicit null checks with early returns to fail fast: `if (!webContents) return null;`
- Use conditional assignment or property existence checks to preserve intended default values instead of unconditionally assigning potentially undefined values

Example implementation:
```ts
// Good: Optional chaining and explicit null check
const archive = getOrCreateArchive(asarPath);
if (!archive) {
  if (options?.throwIfNoEntry === true) {
    throw createError(AsarError.INVALID_ARCHIVE, { asarPath });
  }
  return null;
}

// Good: Conditional property assignment to preserve defaults
const urlLoaderOptions = {
  priority: options.priority
};
if ('priorityIncremental' in options) {
  urlLoaderOptions.priorityIncremental = options.priorityIncremental;
}
```

This approach prevents silent failures, maintains type safety, and ensures predictable behavior when dealing with nullable values.

---

## Ensure algorithmic determinism

<!-- source: astral-sh/ruff | topic: Algorithms | language: Other | updated: 2025-06-24 -->

When implementing algorithms for code analysis, type checking, or pattern matching, ensure they produce consistent and deterministic results for the same inputs. Edge cases should be explicitly handled rather than making assumptions.

Key practices:
1. Use deterministic data structures when order matters (e.g., IndexMap instead of HashMap when processing needs to be order-sensitive)
2. Validate success conditions explicitly rather than assuming failure
3. Test edge cases thoroughly to prevent unexpected behavior

Example of problematic code:
```python
# Incorrect: Unconditionally reporting error without checking if a match was found
def check_overloads(call_site, overloads):
    for overload in overloads:
        if arity_matches(call_site, overload):
            # Missing validation! We found a potential match but didn't verify it
            pass
    # Incorrectly assumes failure even when a match might exist
    report_no_matching_overload(call_site)
```

Improved implementation:
```python
# Correct: Explicitly track success and only report error when needed
def check_overloads(call_site, overloads):
    potential_matches = []
    for overload in overloads:
        if arity_matches(call_site, overload):
            potential_matches.append(overload)
    
    # Only report error if truly no matches were found
    if not potential_matches:
        report_no_matching_overload(call_site)
    else:
        # Process potential matches further
        validate_matches(call_site, potential_matches)
```

Non-deterministic algorithms can introduce subtle bugs that are difficult to reproduce and debug. By ensuring deterministic behavior and explicit validation of conditions, you can create more robust and maintainable code.

---

## Use specific semantic names

<!-- source: microsoft/vscode | topic: Naming Conventions | language: TypeScript | updated: 2025-06-23 -->

Choose specific, descriptive names for identifiers that accurately reflect their purpose and behavior. Avoid generic terms or ambiguous names that could lead to confusion. Names should be self-documenting and convey precise meaning.

Key guidelines:
- Add clarifying prefixes/suffixes to distinguish similar concepts
- Avoid language keywords as identifiers
- Use names that reflect the exact functionality

Example - Improving name specificity:

```typescript
// ❌ Ambiguous or generic names
class AiRelatedInformation { }
function isPath(string: string) { }
interface SearchOptions { }

// ✅ Specific, semantic names
class AiSearchSettingKeysProvider { }
function isPathLike(text: string) { }
interface RipgrepTextSearchOptions { }
```

This helps prevent confusion, makes code more self-documenting, and reduces the need for additional clarifying comments.

---

## Precise CI Workflows

<!-- source: mermaid-js/mermaid | topic: CI/CD | language: Yaml | updated: 2025-06-23 -->

CI workflows should be precise, minimal, and predictable:

- Trigger only when needed: narrow `on: pull_request.paths` (avoid overly broad selectors like `**/*.js` unless required). If the PR doesn’t touch dependency inputs, the lockfile validation workflow shouldn’t run.
- Avoid unnecessary lockfile diffs: don’t update/recommit `pnpm-lock.yaml` unless the PR actually changes what would require regeneration; this reduces merge-conflict risk.
- Keep workflows DRY/organized: prefer integrating checks (e.g., Shellcheck) into existing shared lint workflows. When moving jobs/steps, ensure `permissions` are set at the correct (job) level.
- Harden scheduled runs: use a cron offset rather than exact hour boundaries to reduce delay/drop risk.
- Use stable bot identity for automated commits: for commits created by scheduled/automation runs, set `author_name`/`author_email` to the GitHub Actions bot identity.

Example trigger narrowing:
```yml
on:
  pull_request:
    paths:
      - 'pnpm-lock.yaml'
      - '**/package.json'
# Avoid adding broad patterns like '**/*.js' unless lockfile validation is truly needed for those changes.
```

---

## validate configuration changes

<!-- source: prettier/prettier | topic: Configurations | language: Other | updated: 2025-06-23 -->

Configuration files require careful validation to ensure they work as intended and don't introduce unintended side effects. This includes verifying ignore patterns don't create parent-child conflicts, understanding rule severity implications, and confirming dependency changes are expected.

For ignore patterns, ensure re-inclusion rules don't conflict with parent directory exclusions:
```
# Bad: Can't re-include files in ignored parent directories
/tests/format/**/*.*
!/tests/format/**/format.test.js

# Good: Re-include parent directories first
/tests/format/**/*.*
!/tests/format/**/*.*/
!/tests/format/**/format.test.js
```

For rule configurations, understand the difference between "error" and "warn" severity levels and use appropriate tooling flags like `--max-warnings=0` to enforce standards consistently.

For dependency changes, use tools like `yarn why` to understand why specific versions exist and `yarn-deduplicate` to clean up duplicate dependencies before merging.

Always test configuration changes locally and verify they produce the expected behavior across different scenarios.

---

## Documentation formatting standards

<!-- source: neovim/neovim | topic: Code Style | language: Txt | updated: 2025-06-23 -->

Ensure documentation follows consistent formatting standards to improve readability and maintainability. This includes proper indentation of code blocks for syntax highlighting, clear separation of examples with individual explanatory comments, and concise organization of related information.

Key formatting requirements:
- Indent all code blocks properly for syntax highlighting to work correctly
- Provide separate, clear comments for each code example rather than grouping them under a single ambiguous comment
- Condense related bullet points or information into concise, single entries when possible

Example of improved formatting:
```lua
-- Install "plugin1" and use greatest available version
'https://github.com/user/plugin1',

-- Same as above, but using full table syntax for additional options
{ source = 'https://github.com/user/plugin2' },
```

Rather than:
```lua
-- Install as "plugin1"/"plugin2" and use greatest available version
'https://github.com/user/plugin1',
{ source = 'https://github.com/user/plugin2' },
```

This approach prevents confusion about whether examples represent single or multiple operations and ensures each example's purpose is immediately clear to readers.

---

## Verify union attribute access

<!-- source: astral-sh/ruff | topic: Null Handling | language: Markdown | updated: 2025-06-23 -->

When working with union types in Python, always verify that all components of the union have the attributes you're trying to access or modify. Failure to do so can lead to runtime errors when the code attempts to access undefined attributes.

For attribute access on unions:
1. Check that all possible types in the union support the attribute you're accessing
2. Use conditional checks or type guards to narrow the union before accessing type-specific attributes
3. Handle the case where an attribute might be missing

```python
from typing import Union

class A:
    pass  # No 'x' attribute

class B:
    x: int  # Has 'x' attribute

# Unsafe pattern - might cause runtime errors:
def unsafe(obj: Union[A, B]):
    obj.x = 42  # Error: possibly-unbound-attribute
    
# Safe pattern - check type first:
def safe(obj: Union[A, B]):
    if isinstance(obj, B):
        obj.x = 42  # Safe, we've verified this is type B
        
# Alternative safe pattern - use hasattr:
def also_safe(obj: Union[A, B]):
    if hasattr(obj, "x"):
        obj.x = 42  # Safe, we've verified attribute exists
```

Similarly, when using the `del` statement, track deleted variables carefully and avoid accessing them after deletion to prevent "unresolved-reference" errors.

---

## Resolve naming conflicts clearly

<!-- source: Homebrew/brew | topic: Naming Conventions | language: Markdown | updated: 2025-06-23 -->

When naming components, packages, or files that conflict with existing names in your system or related ecosystems, follow a systematic approach to ensure uniqueness while maintaining semantic clarity:

1. First attempt: Prepend the vendor or developer name followed by a hyphen
   ```
   # Instead of just:
   unison.rb
   
   # Use:
   panic-unison.rb
   ```

2. If conflicts persist: Add descriptive suffixes that clarify the purpose or nature of the item
   ```
   # For different implementations of the same concept:
   appium (formula)
   appium-desktop (cask)
   
   # For application variants:
   angband (formula)
   angband-app (cask)
   ```

3. Maintain consistency with naming conventions in other systems (e.g., other package managers) when your component exists across multiple ecosystems, making only minimal adjustments required by your specific naming conventions.

This approach ensures names remain unique, descriptive, and intuitive, making the codebase more maintainable and reducing confusion for developers working across related systems.

---

## defer expensive operations

<!-- source: neovim/neovim | topic: Performance Optimization | language: Txt | updated: 2025-06-23 -->

Avoid performing expensive operations (like module loading, event emissions, or resource allocation) until they are actually needed. This pattern significantly improves startup time and runtime performance by reducing unnecessary work.

Key strategies:
- Move `require` calls from initialization code into the actual function implementations
- Remove or consolidate unnecessary events/operations that create overhead
- Defer resource-intensive setup until first use

Example of lazy require pattern:
```lua
-- Instead of eager loading at plugin initialization:
local foo = require("foo")
vim.api.nvim_create_user_command("MyCommand", function()
    foo.do_something()
end, {})

-- Defer the require until command execution:
vim.api.nvim_create_user_command("MyCommand", function()
    local foo = require("foo")  -- Load only when needed
    foo.do_something()
end, {})
```

This approach ensures that modules and their dependencies are only loaded when the functionality is actually used, rather than eagerly loading everything at startup. The same principle applies to other expensive operations like network calls, file I/O, or complex computations.

---

## avoid panics gracefully

<!-- source: helix-editor/helix | topic: Error Handling | language: Rust | updated: 2025-06-22 -->

Replace panics, expects, and unwraps with graceful error handling that provides user feedback and allows the system to continue operating. Instead of crashing the application, log errors appropriately and return early or set status messages for the user.

For example, instead of:
```rust
let config = debugger.config.clone();
let result = self
    .dap_servers
    .start_client(Some(socket), &config.expect("No config found"));
```

Use:
```rust
let config = match debugger.config.clone() {
    Some(config) => config,
    None => {
        log::error!("No config found for debugger");
        return true;
    }
};
let result = self.dap_servers.start_client(Some(socket), &config);
```

Similarly, replace panics with status line errors:
```rust
// Instead of: panic!("Expected non-empty argument roots.")
if roots.is_empty() {
    cx.editor.set_error("Expected non-empty argument roots");
    return;
}
```

This approach improves user experience by preventing crashes and providing meaningful feedback about what went wrong, while allowing the application to continue functioning.

---

## Optimize cache sharing strategies

<!-- source: astral-sh/uv | topic: Caching | language: Markdown | updated: 2025-06-22 -->

Select the appropriate cache sharing approach based on your execution environment to maximize performance and efficiency. When working with containerized applications:

1. For local development or long-running VMs:
   - Use cache mounts to persist the cache between container runs
   - Mount to the standard cache location (e.g., `~/.cache/uv`)

2. For CI environments (both parallel and sequential):
   - Use mounted volumes to share cache across containers
   - This reduces network traffic and speeds up dependency installation

Example for sharing cache in Docker containers:
```yaml
# Docker container cache sharing
volumes:
  - ./cache:/root/.cache/uv
```

Keep cache configurations simple by default and only add specialized invalidation patterns when necessary. For most cases, the default cache behavior is sufficient.

---

## Environment variable best practices

<!-- source: astral-sh/uv | topic: Configurations | language: Rust | updated: 2025-06-21 -->

When implementing environment variable configuration:

1. Follow standard environment variable conventions:
- Use uppercase with underscores (e.g., `NO_COLOR`, `FORCE_COLOR`)
- Validate non-empty values for boolean flags
- Support standard environment variables where applicable (e.g., `NO_COLOR`, `FORCE_COLOR`, `CLICOLOR_FORCE`)

2. Document environment variables clearly:
- Specify expected value formats and constraints
- Document the precedence order when multiple configuration methods exist
- Include examples of valid values

Example:
```rust
// Bad - No validation or documentation
if std::env::var_os("FORCE_COLOR").is_some() {
    ColorChoice::Always
}

// Good - Validates non-empty value and documents behavior
/// Controls color output. When set to a non-empty value, forces color output
/// regardless of terminal capabilities.
/// Takes precedence over NO_COLOR and --color settings.
if let Some(force_color) = std::env::var_os("FORCE_COLOR") {
    if !force_color.is_empty() {
        ColorChoice::Always
    }
}
```

3. Establish clear precedence rules:
- Document which settings take precedence (e.g., CLI flags vs environment variables)
- Consider standard environment variables first
- Fall back to custom environment variables before defaults

4. Provide validation and feedback:
- Validate environment variable values early
- Provide clear error messages for invalid values
- Consider warning on deprecated or conflicting configurations

---

## Use structured model metadata

<!-- source: zed-industries/zed | topic: AI | language: Rust | updated: 2025-06-21 -->

Represent AI model information using structured data rather than hardcoded enumerations or conditionals. Store capabilities, limitations, and features as structured fields that can be queried at runtime. This approach simplifies adding new models, detecting feature support, and adapting to model updates without requiring extensive code changes.

For example, instead of:
```rust
fn supports_vision(&self) -> bool {
    match self {
        Self::Gpt4o | Self::Gpt4_1 | Self::Claude3_5Sonnet => true,
        _ => false,
    }
}
```

Use:
```rust
struct Model {
    id: String,
    name: String,
    capabilities: ModelCapabilities,
    // ...
}

struct ModelCapabilities {
    // ...
    supports: ModelSupportedFeatures,
}

struct ModelSupportedFeatures {
    #[serde(default)]
    vision: bool,
    // ...
}

impl Model {
    pub fn supports_vision(&self) -> bool {
        self.capabilities.supports.vision
    }
}
```

This data-driven approach is more maintainable when integrating new AI models and reduces the risk of errors when model capabilities change. It also enables more efficient filtering and selection of models based on required capabilities.

---

## Prefer safe optional handling

<!-- source: ghostty-org/ghostty | topic: Null Handling | language: Swift | updated: 2025-06-21 -->

Always use Swift's built-in mechanisms for safely handling optional values instead of force unwrapping or manual nil handling. Specifically:

1. Use optional binding (`if let`, `guard let`) instead of checking for nil and force unwrapping:

```swift
// Avoid this pattern
if savedWindowFrame != nil {
    let originalFrame = savedWindowFrame!  // Risky force unwrap
}

// Prefer this pattern
if let savedWindowFrame {
    let originalFrame = savedWindowFrame  // Safe access
}
```

2. Use collection transformation methods like `flatMap` or `compactMap` to handle optional collections elegantly:

```swift
// Avoid this pattern
return controllers.reduce([]) { result, c in
    result + (c.surfaceTree.root?.leaves() ?? [])
}

// Prefer this pattern
return controllers.flatMap {
    $0.surfaceTree.root?.leaves() ?? []
}
```

3. Always add appropriate guards to check if objects exist within expected hierarchies or collections before performing operations:

```swift
@IBAction func toggleMaximize(_ sender: Any) {
    guard let window = window else { return }
    guard surfaceTree.contains(sender) else { return }  // Check hierarchy membership
    // Implementation...
}
```

These patterns make code more concise, readable, and less prone to runtime crashes due to unexpected nil values.

---

## Document configuration alternatives

<!-- source: vercel/turborepo | topic: Configurations | language: Markdown | updated: 2025-06-21 -->

When documenting commands or tools that can be executed in different ways based on configuration settings (like global vs. local installation), always explicitly describe all alternatives with clear, consistent labeling. Include examples for each configuration option to ensure users can follow instructions regardless of their environment setup.

For example:
```
# With global installation
turbo dev

# Without global installation, use your package manager
npx turbo dev
yarn exec turbo dev
pnpm exec turbo dev
```

This approach makes documentation more inclusive and prevents confusion when users have different environment configurations. It's especially important for tools that offer multiple execution paths depending on how they're installed or configured.

---

## Standardize package manager commands

<!-- source: vercel/turborepo | topic: CI/CD | language: Markdown | updated: 2025-06-21 -->

Ensure all package manager commands in documentation and CI/CD scripts follow the correct syntax for the specific package manager being used, especially in monorepo environments. Package manager flags should be positioned correctly according to each tool's specifications to prevent pipeline failures.

When documenting commands for monorepo tools like Turborepo:
1. Clearly distinguish between globally installed and locally installed usage
2. Place package manager flags in their correct position
3. When possible, provide generic guidance that works across different package managers

Example:
```
# Incorrect command (flag placement issue)
pnpm test:interactive -F turborepo-tests-integration

# Correct command
pnpm --filter turborepo-tests-integration test:interactive

# For documentation, consider a more generic approach:
# Without global turbo, use your package manager:
npx turbo build    # for npm
yarn dlx turbo build    # for yarn
pnpm exec turbo build    # for pnpm
```

Proper command syntax is critical for successful CI/CD pipelines, as incorrect commands will cause builds to fail and interrupt deployment workflows.

---

## Prefer flat control flow

<!-- source: ghostty-org/ghostty | topic: Code Style | language: Swift | updated: 2025-06-21 -->

Minimize code nesting by using Swift features like `guard` statements and early returns instead of deeply nested if-else structures. When multiple code branches end with a return statement, avoid nesting with `else` clauses.

Instead of:
```swift
if index == count {
    return try body(accumulated)
} else {
    // More nested code here
}
```

Prefer:
```swift
if index == count {
    return try body(accumulated)
}
// Continue with the flow without nesting
```

Or consider using `guard` statements for early returns:
```swift
guard case .split(let c) = node else { return }
// Now work with the unwrapped variable
```

This approach makes code more scannable, easier to follow, and less prone to the "pyramid of doom" issue that can happen with multiple levels of nesting.

---

## Initialize before dereferencing

<!-- source: neovim/neovim | topic: Null Handling | language: C | updated: 2025-06-20 -->

Always ensure buffers, containers, and data structures are properly initialized before passing them to functions that will dereference them. This prevents null pointer dereferences and undefined behavior.

Key practices:
1. **Initialize buffers before use**: When using dynamic containers like kvec, ensure they are properly sized before passing to functions that access their contents
2. **Use null safety annotations**: Apply `FUNC_ATTR_NONNULL_ALL` and similar attributes to function parameters that must not be null
3. **Make precise assertions**: Use specific assertions like `assert(argc > 0)` rather than `assert(argc >= 0)` when zero values are not valid
4. **Handle potentially null returns**: When calling functions like `os_getenv()` that can return null, check the result before dereferencing

Example from the codebase:
```c
// Before: Potential null dereference
if (swap_exists_action != SEA_NONE) {
  choice = (sea_choice_T)do_dialog(VIM_WARNING, _("VIM - ATTENTION"), msg.items, ...);
}

// After: Ensure buffer is initialized
kv_resize(*msg, IOSIZE);  // Initialize buffer before use
if (swap_exists_action != SEA_NONE) {
  choice = (sea_choice_T)do_dialog(VIM_WARNING, _("VIM - ATTENTION"), msg.items, ...);
}
```

This approach prevents static analysis tools from flagging potential null dereferences and ensures runtime safety by establishing clear contracts about what data must be valid before use.

---

## Define explicit error sets

<!-- source: ghostty-org/ghostty | topic: Error Handling | language: Other | updated: 2025-06-20 -->

Always define explicit error sets for functions that can fail, rather than using inferred error sets. This makes error handling more maintainable and helps catch missing error cases during development. The error set should be defined at the function level, even for simple APIs.

Example:
```zig
// Instead of:
pub fn init(alloc: Allocator, opts: rendererpkg.Options) !OpenGL {
    // ...
}

// Do this:
const InitError = error{
    OutOfMemory,
    InvalidVersion,
    DeviceNotFound,
};

pub fn init(alloc: Allocator, opts: rendererpkg.Options) InitError!OpenGL {
    // ...
}
```

This approach:
1. Makes all possible errors explicit in the API
2. Helps catch missing error handling during development
3. Improves API documentation
4. Makes it easier to handle specific error cases

Even for wrapper functions or simple APIs, defining the error set helps maintain consistency and makes future modifications safer by forcing explicit consideration of error cases.

---

## Clear and relevant comments

<!-- source: astral-sh/ruff | topic: Code Style | language: Python | updated: 2025-06-20 -->

Ensure all comments in the codebase provide value and clarity rather than creating confusion. Remove comments that are:

1. Not applicable to the current framework (e.g., linter directives for tools you're not using)
2. Potentially misleading about code behavior or intent
3. Redundant or no longer relevant to the surrounding code

In test files, be particularly cautious with comments that could be misinterpreted about what's being tested. For example, avoid trailing comments that might suggest a different behavior than what the test is actually checking.

Example of problematic comments:
```python
# pylint: disable=unused-import  # Not helpful if not using pylint
foo.__dict__.get("not__annotations__")  # RUF061  # Misleading - suggests this should trigger a warning
```

Example of improved approach:
```python
# Cases that should NOT trigger the violation
foo.__dict__.get("not__annotations__")
```

Regularly review and clean up comments when code changes make them obsolete. Comments should enhance understanding, not create confusion.

---

## Support configuration extension patterns

<!-- source: astral-sh/ruff | topic: Configurations | language: Rust | updated: 2025-06-19 -->

When designing configuration systems, provide both replacement and extension options for list-based settings to give users flexibility in how they modify default configurations.

For list-based configurations, consider implementing:
1. A base option for complete replacement (`allow_abc_meta_bases`)
2. An extension option that appends to defaults (`extend_abc_meta_bases`)

This approach allows users to either:
- Override the entire list when they need complete control
- Add to the existing defaults when they only need minor adjustments

```rust
#[option(
    default = r#"["typing.Protocol", "typing_extensions.Protocol"]"#,
    value_type = "list[str]",
    example = r#"allow-abc-meta-bases = ["my_package.SpecialBaseClass"]"#
)]
pub allow_abc_meta_bases: Vec<String>,

#[option(
    default = r#"[]"#,
    value_type = "list[str]", 
    example = r#"extend-abc-meta-bases = ["my_package.SpecialBaseClass"]"#
)]
pub extend_abc_meta_bases: Vec<String>,
```

When implementing the options, combine them at the settings level rather than requiring consumers to check both settings:

```rust
// In your settings structure
pub struct Settings {
    // Combined at initialization time
    pub allowed_bases: FxHashSet<String>,
}

// When constructing settings
let mut allowed_bases = options.allow_abc_meta_bases.into_iter().collect::<FxHashSet<_>>();
allowed_bases.extend(options.extend_abc_meta_bases.iter().cloned());
```

This pattern promotes cleaner code that consumes the settings, making it less error-prone and easier to maintain.

---

## Optimize algorithmic complexity first

<!-- source: microsoft/vscode | topic: Algorithms | language: TypeScript | updated: 2025-06-19 -->

When implementing algorithms, prioritize reducing computational complexity before adding special cases or optimizing for specific scenarios. Key practices:

1. Identify and eliminate O(n²) operations, especially nested loops and repeated array operations
2. Use appropriate data structures based on access patterns
3. Combine multiple passes into single operations where possible

Example - Converting O(n²) to O(n):

```typescript
// Poor: O(n²) complexity with multiple array operations
selections = selections.filter((s, idx, arr) => {
    return arr.map(sel => sel.endLineNumber)
              .indexOf(s.endLineNumber) === idx;
});

// Better: O(n) complexity with single pass
const seen = new Set();
const uniqueSelections = [];
for (const selection of selections) {
    if (!seen.has(selection.endLineNumber)) {
        seen.add(selection.endLineNumber);
        uniqueSelections.push(selection);
    }
}
```

When using Set operations, ensure object identity works as expected for your data type. For complex objects like URIs, implement custom equality comparisons or use appropriate key extraction.

---

## Code example consistency

<!-- source: vitejs/vite | topic: Code Style | language: Markdown | updated: 2025-06-19 -->

Ensure code examples in documentation and comments are syntactically correct and properly marked with the appropriate language identifier. This maintains a professional appearance and prevents readers from copying incorrect code.

Key guidelines:
- Match language markers to the syntax used (e.g., use ```ts for TypeScript syntax with generics)
- Include all necessary syntax elements like commas and semicolons
- Avoid mixing TypeScript and JavaScript syntax in examples marked as plain JavaScript

Example - INCORRECT:
```js
function myPlugin() {
  const state = new Map<Environment, { count: number }>()
  return {
    name: 'my-plugin',
    buildStart() {
      state.set(this.environment, { count: 0 })
    // Missing comma here!
    transform(code) {
      // ...
    }
  }
}
```

Example - CORRECT:
```ts
function myPlugin() {
  const state = new Map<Environment, { count: number }>()
  return {
    name: 'my-plugin',
    buildStart() {
      state.set(this.environment, { count: 0 })
    }, // Proper comma after function
    transform(code) {
      // ...
    }
  }
}
```

Or alternatively with plain JS:
```js
function myPlugin() {
  const state = new Map()
  return {
    name: 'my-plugin',
    buildStart() {
      state.set(this.environment, { count: 0 })
    },
    transform(code) {
      // ...
    }
  }
}
```

---

## mark experimental configuration features

<!-- source: electron/electron | topic: Configurations | language: Markdown | updated: 2025-06-18 -->

Always mark experimental and deprecated configuration options with appropriate stability indicators in documentation. Use `_Experimental_` for features under active development and `_Deprecated_` for features being phased out. This helps developers make informed decisions about which configuration options are safe for production use.

For experimental features, consider including additional context about stability expectations:

```markdown
* `windowStateRestoreOptions` [WindowStateRestoreOptions](window-state-restore-options.md?inline) (optional) - Options for saving and restoring window state: position, size, maximized state, etc. _Experimental_

* `deprecatedPasteEnabled` boolean (optional) - Whether to enable the `paste` [execCommand](https://developer.mozilla.org/en-US/docs/Web/API/Document/execCommand). Default is `false`. _Deprecated_

* `frozenIntrinsics` boolean (optional) - Experimental option for passing [`--frozen-intrinsics`](https://nodejs.org/api/cli.html#--frozen-intrinsics) to Node.js.
```

For command-line switches marked as experimental in Node.js docs, maintain consistency by flagging them appropriately in Electron documentation as well. This practice ensures developers understand the maturity and support level of configuration options they're considering.

---

## Prefer explicit nil handling

<!-- source: Homebrew/brew | topic: Null Handling | language: Ruby | updated: 2025-06-17 -->

Handle nil values explicitly and consistently to improve code clarity and type safety. Follow these guidelines:

1. Use early returns for nil validation:
```ruby
# Bad
def process_data
  if data.present?
    # process data
  end
end

# Good
def process_data
  return if data.blank?
  # process data
end
```

2. Use .presence for nil/empty string handling:
```ruby
# Bad
name = input.empty? ? nil : input

# Good
name = input.presence
```

3. Prefer raising errors over returning nil when appropriate:
```ruby
# Bad
def fetch_config
  config = load_config
  config if config.valid?
end

# Good
def fetch_config
  config = load_config
  raise Error, "Invalid config" unless config.valid?
  config
end
```

4. Use proper type signatures for nullable values:
```ruby
# Bad
sig { returns(String) }
def optional_value
  @value # might be nil!
end

# Good
sig { returns(T.nilable(String)) }
def optional_value
  @value
end
```

This approach improves code readability, makes nil-handling intentions clear, and helps catch potential nil-related issues early through static analysis.

---

## Standardize platform-agnostic configuration

<!-- source: zed-industries/zed | topic: Configurations | language: Rust | updated: 2025-06-17 -->

Ensure configuration handling is consistent and platform-agnostic by following these guidelines:

1. Use environment variables with fallbacks:
```rust
// Good
let sample_count = std::env::var("ZED_SAMPLE_COUNT")
    .or_else(|_| std::env::var("ZED_PATH_SAMPLE_COUNT"))
    .unwrap_or_default();

// Bad
let sample_count = std::env::var("ZED_SAMPLE_COUNT").unwrap_or_default();
```

2. Implement proper default values using serde attributes:
```rust
#[derive(Deserialize)]
pub struct Config {
    #[serde(default = "default_true")]
    pub enabled: bool,
    
    #[serde(default)]
    pub custom_path: String,
}
```

3. Use platform-agnostic paths and commands:
```rust
// Good
let config_dir = dirs::config_dir()
    .or_else(|| std::env::var_os("XDG_CONFIG_HOME")
    .map(PathBuf::from));

// Bad
let config_dir = PathBuf::from("/usr/local/etc");
```

4. Provide clear validation for configuration:
- Validate all required fields
- Include schema documentation
- Support cross-platform paths
- Handle missing values gracefully

5. Allow configuration overrides through multiple layers:
- Environment variables
- User configuration files
- System defaults
- Platform-specific defaults

This ensures configurations work consistently across different platforms while maintaining flexibility and robustness.

---

## Precise type narrowing

<!-- source: astral-sh/ruff | topic: Algorithms | language: Markdown | updated: 2025-06-17 -->

Implement sound type narrowing algorithms that balance precision with correctness. When narrowing types:

1. For direct assignments, narrow the type to the assigned value's type:
```python
x: int | None = None
x = 42
# x now has type Literal[42]
```

2. For attributes and subscripts, only narrow when the operation is known to be sound:
- Narrow attribute assignments except for properties and descriptors
- Only narrow subscripts for built-in types with well-defined behavior (`list`, `dict`, etc.)
```python
# Sound - regular attribute
obj.attr = "value"  # obj.attr now has type Literal["value"]

# Unsound - property may transform the value
@property
def x(self): return self._x
@x.setter
def x(self, val): self._x = abs(val)
obj.x = -1  # obj.x should still be int, not Literal[-1]
```

3. Reset narrowed types when the base object is reassigned:
```python
c = C()
c.attr = "foo"  # c.attr has type Literal["foo"]
c = C()         # c.attr should revert to its declared type
```

4. For type guards, correctly intersect the original type with the guarded type:
```python
def is_int(x: object) -> TypeIs[int]: ...

def func(x: Any):
    if is_int(x):
        # x has type Any & int
```

Sound type narrowing algorithms prevent false negatives while maintaining precision, allowing for safer and more robust code.

---

## Use direct documentation style

<!-- source: astral-sh/uv | topic: Documentation | language: Markdown | updated: 2025-06-17 -->

Write documentation using direct, clear language that addresses the reader directly. Follow these style guidelines:

1. Use direct address instead of referring to "users" - write "You can configure..." rather than "Users can configure..."

2. Avoid words like "simply" that minimize complexity - recognize that what seems simple to documentation authors may not be obvious to all readers.

3. Maintain consistent formatting for technical elements (HTTP status codes, command options, etc.) throughout documentation.

4. Keep guides focused on common workflows with appropriate detail levels, saving complex explanations for reference documentation.

Example - Instead of:
```
When using the `first-index` strategy, uv will stop searching if it encounters a `401 Unauthorized` 
or `403 Forbidden` response status code. Users can configure which error codes are ignored for an 
index, using the `ignored-error-codes` setting.
```

Write:
```
When using the first-index strategy, uv will stop searching if an HTTP 401 Unauthorized 
or HTTP 403 Forbidden status code is encountered. To ignore additional error codes for an index, 
use the `ignored-error-codes` setting.
```

This style creates documentation that feels more approachable while maintaining technical accuracy.

---

## Structure test fixtures clearly

<!-- source: Homebrew/brew | topic: Testing | language: Ruby | updated: 2025-06-17 -->

Test fixtures should clearly separate input parameters from expected outputs to enhance readability and maintainability. For table-driven tests, use a consistent pattern that explicitly distinguishes between test inputs and expected results. This approach makes tests more understandable and easier to maintain over time.

A well-structured table-driven test might look like:

```ruby
tests = {
  "generic tarball URL": {
    params: {
      url: "http://digit-labs.org/files/tools/synscan/releases/synscan-5.02.tar.gz",
    },
    expected: {
      name: "synscan",
      version: "5.02",
    },
  },
  "with version override": {
    params: {
      url: "http://digit-labs.org/files/tools/synscan/releases/synscan-5.02.tar.gz",
      version: "3.40",
    },
    expected: {
      name: "synscan",
      version: "3.40",
    }
  },
}

tests.each do |description, test|
  it "processes #{description}" do
    result = process_with(test[:params])
    expect(result).to eq(test[:expected])
  end
end
```

This structure makes it immediately clear what inputs are being provided and what outputs are expected, improving test readability and making failures easier to diagnose.

---

## async destruction safety

<!-- source: electron/electron | topic: Concurrency | language: Other | updated: 2025-06-17 -->

When destroying objects asynchronously to avoid crashes from observer notifications or other synchronous destruction issues, ensure proper cleanup ordering and add defensive null checks to handle race conditions.

Key practices:
1. **Move destruction to async context**: Use task runners to defer destruction when synchronous cleanup causes crashes due to active observers or notifications
2. **Reset pointers immediately**: After moving objects to async destruction, immediately set the original pointer to null to prevent use-after-move
3. **Add defensive null checks**: In methods that might be called during async destruction, add null checks before accessing potentially destroyed objects
4. **Explicit resource cleanup**: For resources requiring manual shutdown (like dbus::Bus), ensure cleanup methods are called before destruction

Example from the discussions:
```cpp
// Instead of synchronous destruction that crashes:
// managed_devtools_web_contents_.reset();

// Use async destruction:
embedder_message_dispatcher_.reset();
content::GetUIThreadTaskRunner({})->PostTask(
    FROM_HERE,
    base::BindOnce(
        [](std::unique_ptr<content::WebContents> web_contents) {},
        std::move(managed_devtools_web_contents_)));
managed_devtools_web_contents_ = nullptr;

// Add defensive checks in methods:
if (!GetDevToolsWebContents())
  return;
```

This pattern prevents crashes from premature destruction while maintaining system stability during async cleanup operations.

---

## configuration consistency validation

<!-- source: hyprwm/Hyprland | topic: Configurations | language: Other | updated: 2025-06-17 -->

When modifying configuration options, ensure changes are consistently applied across all relevant locations including default configuration files, documentation, example configs, and related codebases. Configuration inconsistencies create user confusion and maintenance burden.

This reviewer addresses the common issue where developers update configuration in one location but forget to synchronize changes elsewhere. For example, when updating brightness control settings, the change must be reflected in both the main config and the default config header file.

Example of proper consistency:
```cpp
// In defaultConfig.hpp
bindel = ,XF86MonBrightnessUp, exec, brightnessctl -e4 -n2 set 5%+

// In example/hyprland.conf  
bindel = ,XF86MonBrightnessUp, exec, brightnessctl -e4 -n2 set 5%+
```

Before merging configuration changes, verify:
- Default configuration files are updated
- Example configurations reflect the changes  
- Documentation and wiki entries are synchronized
- Related configuration files use consistent syntax and values
- Environment variables are set in appropriate locations rather than duplicated

This practice prevents user confusion from conflicting examples and reduces maintenance overhead from scattered, inconsistent configuration references.

---

## prefer CSS over JavaScript

<!-- source: microsoft/playwright | topic: Code Style | language: TSX | updated: 2025-06-17 -->

Use CSS solutions instead of JavaScript state management for simple styling and interactions. This approach improves maintainability, reduces complexity, and follows web standards best practices.

Examples of when to apply this:
- Use CSS `:hover` pseudo-classes instead of `onMouseEnter`/`onMouseLeave` event handlers
- Implement show/hide behavior with CSS `display` or `visibility` properties rather than React state
- Apply styling through CSS classes instead of inline styles

Example transformation:
```tsx
// Instead of JavaScript state management:
const [isOpen, setIsOpen] = useState(false);
return (
  <div onMouseEnter={() => setIsOpen(true)} onMouseLeave={() => setIsOpen(false)}>
    {isOpen && <div className="dropdown-menu">...</div>}
  </div>
);

// Use CSS-based solution:
return (
  <div className="dropdown">
    <div className="dropdown-menu">...</div>
  </div>
);

/* CSS */
.dropdown:not(:hover) .dropdown-menu {
  display: none;
}
```

This approach reduces JavaScript complexity, improves performance, and makes the code more maintainable by leveraging native browser capabilities.

---

## Ensure async error cleanup

<!-- source: electron/electron | topic: Error Handling | language: TypeScript | updated: 2025-06-16 -->

Always ensure cleanup code executes and avoid creating dangling promises in error handling scenarios. Use try-catch-finally patterns for guaranteed cleanup, and avoid making error handlers async unless you properly handle promise rejections.

For test assertions and cleanup operations, collect data first, then perform assertions outside the error-prone section:

```javascript
// Good: Assertions run even if errors occur
const lines = [];
let handle = null;
try {
  handle = await fs.open(file);
  for await (const line of handle.readLines()) {
    lines.push(line);
  }
} finally {
  await handle?.close();
  await fs.rm(file, { force: true });
}
expect(lines.length).to.equal(1);
expect(lines[0]).to.equal('before exit');
```

For async operations, use try-catch-finally instead of making error handlers async:

```javascript
// Good: Proper cleanup with try-catch-finally
loadESM(async (esmLoader: any) => {
  try {
    await esmLoader.import(main, undefined, Object.create(null))
  } catch (e) {
    process.emit('uncaughtException', err);
  } finally {
    appCodeLoaded!();
  }
});

// Avoid: Making error handlers async creates dangling promises
capturer._onerror = (error: string) => {
  // Handle synchronously or use .then() for promises
  winsOwnedByElectronProcess.then(() => {
    stopRunning();
    reject(error);
  });
};
```

This pattern ensures that cleanup operations always execute and prevents unhandled promise rejections that can lead to application instability.

---

## Safe optional handling

<!-- source: microsoft/terminal | topic: Null Handling | language: C++ | updated: 2025-06-16 -->

Always use safe patterns when working with optional, nullable, or potentially empty types. Avoid direct comparisons with optional values and ensure proper initialization of nullable members.

Key practices:
- Use `.value_or(default)` instead of direct comparisons with optional types
- Initialize nullable member variables explicitly (e.g., `_richBlock{ nullptr }`)
- Check for null/empty state before dereferencing (use ternary operators when needed)
- Be cautious with move operations that may leave objects in empty states

Example of unsafe vs safe optional handling:
```cpp
// Unsafe - direct comparison with optional
if (modernValue == 1u) // optional<uint32_t> != uint32_t comparison

// Safe - use value_or for truthy check
if (modernValue.value_or(0) != 0)

// Unsafe - assuming non-null without check
theme.Pane().ActiveBorderColor() // crashes if Pane() returns null

// Safe - null check with ternary
const auto paneActiveBorderColor = theme.Pane() ? theme.Pane().ActiveBorderColor() : nullptr;
```

This prevents crashes from null dereferences, undefined behavior from uninitialized members, and logic errors from improper optional comparisons.

---

## Parameterize similar tests

<!-- source: python-poetry/poetry | topic: Testing | language: Python | updated: 2025-06-15 -->

Use `pytest.mark.parametrize` to consolidate similar test cases instead of duplicating test code. This approach improves maintainability, reduces code duplication, and ensures comprehensive test coverage across different scenarios.

When you find yourself writing multiple test functions that follow the same pattern with different inputs or expected outputs, combine them into a single parameterized test. This makes it easier to add new test cases and ensures consistent testing logic.

Example of consolidating duplicate tests:

```python
# Instead of multiple similar tests:
def test_git_ref_spec_resolve_branch():
    refspec = GitRefSpec(branch="main")
    refspec.resolve(mock_fetch_pack_result)
    assert refspec.ref == b"refs/heads/main"

def test_git_ref_spec_resolve_tag():
    refspec = GitRefSpec(revision="v1.0.0")
    refspec.resolve(mock_fetch_pack_result)
    assert refspec.ref == annotated_tag(b"refs/tags/v1.0.0")

# Use parameterization:
@pytest.mark.parametrize("input_type,input_value,expected_ref", [
    ("branch", "main", b"refs/heads/main"),
    ("revision", "v1.0.0", annotated_tag(b"refs/tags/v1.0.0")),
    ("revision", "abc", b"refs/heads/main"),
])
def test_git_ref_spec_resolve(input_type, input_value, expected_ref):
    kwargs = {input_type: input_value}
    refspec = GitRefSpec(**kwargs)
    refspec.resolve(mock_fetch_pack_result)
    assert refspec.ref == expected_ref
```

This approach is particularly valuable when testing different error conditions, input formats, or configuration options. It also makes it easier to identify gaps in test coverage and add new test cases systematically.

---

## Dynamic configuration handling

<!-- source: hyprwm/Hyprland | topic: Configurations | language: C++ | updated: 2025-06-15 -->

When implementing configuration changes that need to be applied at runtime, follow these practices:

1. **Use reload mechanisms instead of immediate handling**: Don't process configuration changes directly in dispatch functions. Instead, trigger reloads through proper channels.

```cpp
// Don't do this:
if (COMMAND.contains("monitorv2")) {
    g_pConfigManager->handleMonitorv2();
    g_pConfigManager->m_wantsMonitorReload = true;
}

// Do this instead:
g_pEventLoopManager->doLater([this] {
    g_pConfigManager->m_wantsMonitorReload = true;
});
```

2. **Use static pointers for dynamic configuration**: For configuration values that need to change via hyprctl, use static CConfigValue pointers rather than copying values, as this enables runtime updates.

```cpp
// For dynamic config that changes via hyprctl:
static auto PDISABLELOGS = CConfigValue<Hyprlang::INT>("debug:disable_logs");

// Not this (copies value once):
Debug::coloredLogs = std::any_cast<Hyprlang::INT>(m_pConfig->getConfigValue("debug:colored_stdout_logs"));
```

3. **Use existing parsing utilities**: Leverage `configStringToInt` and similar utilities for consistent configuration parsing instead of implementing custom parsing logic.

```cpp
// Use existing utility:
PANIM->second.internalEnabled = configStringToInt(ARGS[1]);

// Instead of custom parsing:
if (ARGS[1] == "on" || ARGS[1] == "true" || ARGS[1] == "1")
    PANIM->second.internalEnabled = true;
```

4. **Check configuration existence properly**: When determining if a user has set a configuration value, use the appropriate methods to check the `set` flag rather than implementing custom existence checking.

This approach ensures configuration changes are processed consistently, can be updated dynamically, and maintain proper state management throughout the application lifecycle.

---

## avoid quadratic complexity

<!-- source: helix-editor/helix | topic: Algorithms | language: Rust | updated: 2025-06-14 -->

When working with data structures, especially ropes and collections, avoid algorithms that result in quadratic time complexity when linear alternatives exist. Common patterns to watch for include repeated indexing operations and nested loops over related data sets.

**Key anti-patterns:**
- Repeatedly indexing into ropes: `(0..=cursor_char).rev().find(|&i| !is_word(text.char(i)))` is O(W*log(N))
- Nested iteration without bounds: `code_actions_on_save.iter().any(|a| match &x.kind { ... })` can be O(M*N)

**Better approaches:**
- Use iterators for rope operations: `text.chars_at(cursor_char).take_while(is_word).count()` is O(log(N)+W)
- Convert frequently-searched collections to HashSet: `let actions_set: HashSet<_> = code_actions_on_save.iter().collect()` makes lookups O(1)
- Leverage built-in optimized methods: use `partition_point` instead of `binary_search_by_key` when you don't need the exact match

Example transformation:
```rust
// Inefficient O(W*log(N)) - repeated rope indexing
let start = (0..=cursor_char)
    .rev()
    .find(|&i| !is_word(text.char(i)))
    .map(|i| i + 1)
    .unwrap_or(0);

// Efficient O(log(N)+W) - iterator-based
let start = cursor_char - text.chars_at(cursor_char)
    .reversed()
    .take_while(|&c| is_word(c))
    .count();
```

Always consider the complexity of your algorithm, especially when dealing with text processing, search operations, or nested data access patterns.

---

## Target documentation to audience

<!-- source: helix-editor/helix | topic: Documentation | language: Other | updated: 2025-06-14 -->

Write documentation that matches both your audience's expertise level and the language's conventional formats. For technical documentation, use language-specific conventions (like Rust's doc comments). For tutorials or learning materials, prefer step-by-step explanations that minimize cognitive load.

Example:
```rust
// Technical API documentation - uses language conventions
/// Processes the input string and returns a formatted result
/// 
/// # Arguments
/// * `input` - The string to process
pub fn process_string(input: &str) -> String { }

// Tutorial/Learning documentation - uses simpler, step-by-step format
// Step 1: First, create a new string variable
// Step 2: Add your text to the variable
// Step 3: Call the process_string function with your variable
```

Consider your audience's familiarity with the codebase and technical concepts when choosing between detailed technical documentation and simplified, step-by-step explanations. Always follow the language's documentation conventions while maintaining appropriate detail level for the target readers.

---

## Names should be descriptive

<!-- source: astral-sh/uv | topic: Naming Conventions | language: Rust | updated: 2025-06-13 -->

Use clear, descriptive names while avoiding redundant qualifiers. Choose full words over abbreviations unless the abbreviated form is widely recognized. When a type or context already implies certain qualities, avoid repeating them in the name.

Good examples:
```rust
// Good: Clear, descriptive names
let preferred = if cfg!(all(windows, target_arch = "aarch64")) { ... }
fn find_pyvenv_cfg_version_conflict(&self) -> Option<(Version, Version)> { ... }

// Bad: Unnecessary qualifiers, abbreviations
let maybe_index_url: Option<&Url> = ...  // Use just 'index_url' - Option implies maybe
let auth_indexes: AuthIndexes = ...      // Use just 'indexes' in auth context
let tool_py_req = ...                    // Use 'tool_python_request' instead
```

Maintain naming consistency with existing codebase patterns. If a particular name is used consistently throughout the codebase (e.g., 's' for pluralization), follow that convention unless there's a compelling reason to change it.

---

## Prefer Rust structural patterns

<!-- source: zed-industries/zed | topic: Code Style | language: Rust | updated: 2025-06-13 -->

Use Rust's structural patterns to write more idiomatic and maintainable code. This includes:

1. Use early returns to reduce nesting:
```rust
// Instead of
if condition {
    if other_condition {
        // deep nesting
    }
} 

// Prefer
if !condition { return }
if !other_condition { return }
// main logic
```

2. Leverage pattern matching and destructuring:
```rust
// Instead of
let response = response.body_mut().read_to_end(&mut body).await?;
if response.status().is_success() {
    // handle success
}

// Prefer
let Some((buffer, buffer_position)) = self.buffer.read(cx)
    .text_anchor_for_position(position, cx) 
else { return };
```

3. Use Rust's type system effectively:
```rust
// Instead of
signature_help_task: Default::default(),

// Prefer
signature_help_task: None,
```

4. Utilize iterator combinators to flatten logic:
```rust
// Instead of
.get_diagnostics(server_id)
    .map(|diag| {
        diag.iter()
            .filter(...)
            .map(...)
            .collect()
    })

// Prefer
.get_diagnostics(server_id)
    .into_iter()
    .flat_map(...)
```

These patterns improve code readability, reduce complexity, and make the code more maintainable by leveraging Rust's built-in features effectively.

---

## Actions workflow best practices

<!-- source: Homebrew/brew | topic: CI/CD | language: Yaml | updated: 2025-06-13 -->

{% raw %}
Use GitHub Actions native features and follow best practices to create maintainable, secure, and reliable CI workflows:

1. **Use working-directory instead of manual cd commands**
   ```yaml
   # DO THIS
   - name: Run command in specific directory
     working-directory: ${{ steps.set-up-homebrew.outputs.repository-path }}
     run: |
       command1
       command2

   # INSTEAD OF THIS
   - name: Run command in specific directory
     run: |
       cd "${{ steps.set-up-homebrew.outputs.repository-path }}"
       command1
       command2
   ```

2. **Pin specific SHA commits for third-party actions**
   ```yaml
   # DO THIS
   - uses: codecov/test-results-action@9739113ad922ea0a9abb4b2c0f8bf6a4aa8ef820 # v1.0.1

   # INSTEAD OF THIS
   - uses: codecov/test-results-action@v1
   ```

3. **Handle all possible job states in conditional logic**
   ```yaml
   update-existing: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped') }}
   ```

4. **Scope permissions to the minimum required level**
   ```yaml
   # DO THIS - scope permissions per job
   jobs:
     build:
       permissions:
         contents: read
         attestations: write
         id-token: write

   # INSTEAD OF THIS - overly broad permissions
   permissions:
     contents: read
     attestations: write
     id-token: write
   ```

These practices improve workflow reliability, security, and maintainability while making troubleshooting easier.
{% endraw %}

---

## Mask sensitive tokens

<!-- source: astral-sh/uv | topic: Security | language: Yaml | updated: 2025-06-13 -->

{% raw %}
Always mask sensitive tokens, credentials, and secrets in CI/CD workflows to prevent accidental exposure in logs or build outputs. In GitHub Actions, use the `::add-mask::` command before outputting or storing sensitive values in environment variables.

Example:
```yaml
- name: "Get AWS CodeArtifact token"
  run: |
    UV_TEST_AWS_TOKEN=$(aws codeartifact get-authorization-token \
      --domain tests \
      --domain-owner ${{ secrets.AWS_ACCOUNT_ID }} \
      --region us-east-1 \
      --query authorizationToken \
      --output text)
    echo "::add-mask::$UV_TEST_AWS_TOKEN"
    echo "UV_TEST_AWS_TOKEN=$UV_TEST_AWS_TOKEN" >> $GITHUB_ENV
```

This practice should be applied consistently for all types of authentication tokens (AWS, GCP, API keys, etc.) to maintain security and prevent credential leakage. Even in private repositories, proper token masking is essential for security best practices and to prevent credentials from being visible in workflow logs that team members can access.
{% endraw %}

---

## Make errors user actionable

<!-- source: astral-sh/uv | topic: Error Handling | language: Rust | updated: 2025-06-12 -->

Error messages should provide clear, actionable information that helps users understand and resolve the problem. Each error should:
1. Include specific context about what failed
2. Explain why it failed
3. When applicable, suggest how to fix it

Example of improving error messages:

```rust
// Instead of:
#[error(transparent)]
ManagedPythonError(#[from] managed::Error),

// Prefer:
#[error("Failed to discover managed Python installations")]
ManagedPythonError(#[from] managed::Error),

// Even better with context and remedy:
#[error("Failed to authenticate with {url}")]
#[error("hint: Check your credentials or configure authentication using UV_INDEX_{index}_USERNAME")]
AuthenticationError { url: String, index: String }
```

When designing error handling:
- Use specific error variants instead of returning Ok(None) for expected failure cases
- Include relevant context (URLs, file paths, version numbers) in error messages
- Add hints or help messages for common failure scenarios
- Distinguish between different failure modes (e.g., missing vs invalid credentials)
- Keep error messages focused on the user's perspective rather than internal implementation details

---

## Synchronous event handlers

<!-- source: microsoft/playwright | topic: Concurrency | language: TypeScript | updated: 2025-06-12 -->

Keep event handlers synchronous to prevent race conditions and timing issues. Async operations within event handlers can cause deadlocks, missed events, and unpredictable behavior.

**Why this matters:**
Event handlers must execute synchronously to ensure proper event ordering and prevent race conditions. When async operations are introduced into event handlers, they can cause events to be missed, create deadlocks with message passing, or lead to cleanup operations happening at the wrong time.

**Guidelines:**
1. **Never make event handlers async** - Event callbacks should complete synchronously
2. **Defer async work** - If async operations are needed, schedule them separately rather than awaiting in the handler
3. **Be careful with cleanup timing** - Removing event listeners immediately can prevent clients from receiving events

**Example of problematic pattern:**
```javascript
// BAD: Async event handler can cause timing issues
private async _onPage(page: Page): Promise<void> {
    this._pages.add(page);
    this.emit(Events.BrowserContext.Page, page);
    await this._mockingProxy?.instrumentPage(page); // This breaks synchronous event flow
}

// BAD: Immediate cleanup prevents event delivery
close() {
    this._socket.close();
    eventsHelper.removeEventListeners(this._eventListeners); // Client never receives 'close' event
}
```

**Better approach:**
```javascript
// GOOD: Keep handler synchronous, defer async work
private _onPage(page: Page): void {
    this._pages.add(page);
    this.emit(Events.BrowserContext.Page, page);
    // Schedule async work separately
    this._instrumentPageAsync(page);
}

private async _instrumentPageAsync(page: Page) {
    await this._mockingProxy?.instrumentPage(page);
}
```

This principle prevents deadlocks, ensures event ordering, and maintains predictable async behavior throughout the application.

---

## Validate before configuration generation

<!-- source: microsoft/terminal | topic: Configurations | language: C++ | updated: 2025-06-12 -->

Always validate system capabilities and existing configuration state before generating new configuration entries or profiles. This prevents unnecessary configuration generation, improves startup performance, and avoids presenting unusable options to users.

Check system prerequisites, existing installations, and user capabilities before creating configuration entries. For example, when generating profile installers, verify if the target software is already installed or if the installation mechanism is available.

Example from PowerShell profile generation:
```cpp
PowershellCoreProfileGenerator powerShellGenerator{};
_executeGenerator(powerShellGenerator);

const auto isPowerShellInstalled = !powerShellGenerator.GetPowerShellInstances().empty();
if (!isPowerShellInstalled)
{
    // Only generate the installer stub profile if PowerShell isn't installed.
    PowershellInstallationProfileGenerator pwshInstallationGenerator{};
    _executeGenerator(pwshInstallationGenerator);
}
```

This approach prevents generating configuration that would be immediately marked for deletion, reduces UI clutter by hiding irrelevant options, and avoids potential startup performance impacts from unnecessary configuration processing. Always consider whether configuration generation should be conditional based on system state rather than generating everything and cleaning up afterward.

---

## Single yield algorithm

<!-- source: astral-sh/ruff | topic: Algorithms | language: Python | updated: 2025-06-12 -->

Context managers must follow a crucial algorithmic constraint: each execution path must yield exactly once. Multiple yields in the same path lead to unpredictable behavior, while no yields prevent proper resource management.

When implementing context managers with `@contextlib.contextmanager`:

1. Ensure mutually exclusive branches if using conditional yields
2. Use early returns to prevent execution of subsequent yields
3. Avoid yields in loops or anywhere that could lead to multiple yields during execution

Example of correct implementation:
```python
@contextlib.contextmanager
def valid_context_manager(condition):
    # Setup code
    try:
        if condition:
            yield "success"
            return  # Early return prevents reaching the next yield
        yield "alternative"
    finally:
        # Cleanup code always executed
        print("Cleaning up")
```

This pattern ensures the algorithm's invariant of "yield exactly once" regardless of which execution path is taken, maintaining reliable resource acquisition and release.

---

## prefer const correctness

<!-- source: electron/electron | topic: Code Style | language: Other | updated: 2025-06-11 -->

Always mark variables, parameters, and methods as `const` when they don't modify state. This improves code safety, enables compiler optimizations, and makes intent clearer to readers.

Apply const in these scenarios:
- **Variables that don't change**: `const auto* command_line = base::CommandLine::ForCurrentProcess();`
- **Parameters that aren't modified**: `bool IsDetachedFrameHost(const content::RenderFrameHost* rfh)`
- **Methods that don't modify object state**: `bool IsWirelessSerialPortOnly() const;`
- **Pointers to immutable data**: `const display::Screen* screen = display::Screen::GetScreen();`

Example transformation:
```cpp
// Before
auto* command_line = base::CommandLine::ForCurrentProcess();
display::Screen* screen = display::Screen::GetScreen();
bool IsDetachedFrameHost(content::RenderFrameHost* rfh);

// After  
const auto* command_line = base::CommandLine::ForCurrentProcess();
const display::Screen* screen = display::Screen::GetScreen();
bool IsDetachedFrameHost(const content::RenderFrameHost* rfh);
```

Const correctness prevents accidental modifications, enables the compiler to catch errors early, and serves as documentation of your code's intent. When in doubt, start with const and remove it only if modification is necessary.

---

## reduce nesting complexity

<!-- source: helix-editor/helix | topic: Code Style | language: Rust | updated: 2025-06-11 -->

Prefer code structures that minimize nesting levels and improve readability through early returns, pattern matching, and avoiding deeply nested assignments.

Use early returns and let-else patterns to reduce nesting:

```rust
// Instead of nested if-let
if let Some(doc) = doc {
    if let Some(version) = document_version {
        if version != doc.version() {
            log::info!("Version mismatch");
            return;
        }
    }
    // process doc
}

// Prefer early returns and let-else
let Some(doc) = self
    .documents
    .values_mut()
    .find(|doc| doc.uri().is_some_and(|u| u == uri))
else {
    return;
};
if let Some(version) = document_version {
    if version != doc.version() {
        log::info!("Version mismatch");
        return;
    }
}
// process doc
```

Use match statements instead of nested conditionals when appropriate, and avoid let blocks that increase indentation unnecessarily. Don't create deeply nested assignments as they are hard to read and don't fit with the codebase style. When possible, use mutable variables in the same scope rather than introducing additional nesting levels.

---

## Clear accurate error messages

<!-- source: microsoft/terminal | topic: Error Handling | language: Other | updated: 2025-06-11 -->

Error messages should be clear, accurate, and contextually appropriate to help users understand what went wrong and how to fix it. Use complete, descriptive terms instead of abbreviations or technical jargon that may confuse users. Ensure error messages accurately reflect the actual capabilities and constraints of the system rather than copying generic messages that may not apply.

Key principles:
- Use full descriptive terms (e.g., "regular expression" instead of "regex")
- Ensure messages match actual system capabilities (don't mention features that aren't supported)
- Make error conditions explicit rather than silently falling back to default behavior
- Test error scenarios to verify message accuracy

Example from the discussions:
```xml
<!-- Better: Clear and complete terminology -->
<value>An invalid regular expression was found.</value>

<!-- Avoid: Abbreviated or potentially misleading terms -->
<value>An invalid regex was found.</value>
```

When encountering unhandled cases, consider using explicit error detection (like assertions) rather than returning empty or default values that mask the underlying problem.

---

## Enforce strong optional types

<!-- source: astral-sh/uv | topic: Null Handling | language: Rust | updated: 2025-06-11 -->

Use strong typing and early validation to handle optional values and prevent null-related issues. Prefer enums and specific types over strings when dealing with optional data, and validate optional values as early as possible in the data flow.

Key practices:
1. Use enums instead of strings for known value sets
2. Leverage bool::then for cleaner optional handling
3. Validate optional data at structure boundaries

Example:
```rust
// Instead of
struct Config {
    kind: String,  // Could be "realm" or "index"
    value: Option<String>
}

// Prefer
enum ConfigKind {
    Realm(String),
    Index(String)
}
struct Config {
    kind: ConfigKind,
    value: Option<String>
}

// Use bool::then for cleaner optional handling
let value = condition.then(|| compute_value());

// Validate optional data early
fn get_project_version(doc: &mut Document) -> Result<Version, Error> {
    let project = doc.get("project")
        .ok_or(Error::MissingProject)?;
    
    let version = project
        .get("version")
        .and_then(Item::as_value)
        .and_then(Value::as_str)
        .ok_or(Error::MissingVersion)?;

    Version::from_str(version)
}

---

## Follow established naming conventions

<!-- source: astral-sh/uv | topic: Naming Conventions | language: Markdown | updated: 2025-06-11 -->

Adhere to established naming conventions for files, variables, functions, and configuration options to maintain consistency and clarity throughout the codebase and documentation.

- Use standardized capitalization for common files (`README.md` instead of `Readme.md`, `LICENSE` without file extension)
- Maintain consistency when referring to environment variables (use either `$HOME` or `~` throughout, don't mix styles)
- Avoid using special name patterns (like dunders `__name__`) for regular functions to prevent confusion
- Choose names that clearly communicate purpose and scope

```python
# Incorrect: Using dunder name for regular function
def __main__():
    process_data()

# Correct: Use standard naming for regular functions
def main():
    process_data()
```

In documentation, maintain consistent reference style:
```
# Inconsistent
- `$XDG_CACHE_HOME/uv` or `~/.cache/uv` on Unix systems

# Consistent
- `$XDG_CACHE_HOME/uv` or `$HOME/.cache/uv` on Unix systems
```

---

## Self-explanatory identifier names

<!-- source: zed-industries/zed | topic: Naming Conventions | language: Json | updated: 2025-06-11 -->

Choose identifier names that clearly convey their purpose without requiring users to understand implementation details. If reviewers struggle to understand what a name means, it likely needs improvement.

When naming functions or settings:
1. Favor descriptive clarity over excessive brevity
2. Remove redundant parts while maintaining meaning
3. When boolean names become awkward, consider using enums instead

**Examples:**
```
// Less clear
"line_number_base_width": 4

// Better - describes what it actually means
"min_line_number_digits": 4
```

```
// Unclear boolean (what does "true" actually mean?)
"focus_skip_active_file": true

// Better as an enum
enum AutoFocus {
    First,
    SkipActive
}
```

```
// Unnecessarily verbose
"workspace::IncreaseOpenDocksSizeByOffset"

// Better - removes redundancy while preserving meaning
"workspace::IncreaseDocksSize"
```

---

## event delegation patterns

<!-- source: zen-browser/desktop | topic: Networking | language: Other | updated: 2025-06-11 -->

When handling events in web applications, especially those involving network-triggered UI updates or real-time data streams, prefer event delegation over individual element listeners for better performance and maintainability. Use container-level event listeners and check the event target rather than attaching listeners to each individual element.

This approach is particularly important when dealing with dynamic content that may be updated based on network responses, websocket messages, or API calls, as it ensures event handlers remain functional even when DOM elements are added or removed dynamically.

Example:
```javascript
// Preferred: Event delegation
gBrowser.tabContainer.addEventListener('dblclick', (event) => {
  if (event.target.matches('.tab-label')) {
    // Handle the event
  }
});

// Avoid: Individual listeners on each element
tabs.forEach(tab => {
  tab.addEventListener('dblclick', handler);
});
```

This pattern reduces memory overhead and ensures consistent behavior when UI elements are dynamically updated from network data sources.

---

## Keep APIs simple JavaScript-like

<!-- source: microsoft/vscode | topic: API | language: TypeScript | updated: 2025-06-09 -->

Design APIs to be simple and idiomatic to JavaScript/TypeScript while maintaining proper encapsulation. Avoid complex type unions, forced undefined parameters, or implementation details leaking through interfaces.

Key principles:
1. Prefer simple classes over discriminated unions
2. Make optional parameters truly optional
3. Maintain clean interface boundaries
4. Follow the API proposal process

Example - Instead of:
```typescript
interface RequestInitiator {
  kind: InitiatorKind.Extension;
  extensionId: string;
} | {
  kind: InitiatorKind.Internal;
  reason: string;
}

function decode(content: Uint8Array, options: { uri: Uri | undefined }): Promise<string>
```

Prefer:
```typescript
class RequestInitiator {
  constructor(
    readonly kind: InitiatorKind,
    readonly identifier: string
  ) {}
}

function decode(content: Uint8Array, options?: { uri?: Uri }): Promise<string>
```

---

## Short-circuit evaluation strategies

<!-- source: astral-sh/uv | topic: Algorithms | language: Rust | updated: 2025-06-09 -->

When implementing search or traversal algorithms, use short-circuit evaluation strategically to avoid unnecessary computation while ensuring correctness. Short-circuiting is beneficial when the first match is sufficient, but can lead to incorrect results when complete information is needed.

For example, when implementing a search function:

```rust
// Good: Use short-circuit when first match is sufficient
fn find_python_installation(installations: &[Installation]) -> Option<&Installation> {
    installations.iter().find(|installation| 
        request.matches_installation(installation))
}

// Good: Use closure to make short-circuit logic clearer
let (db, actual_rev, maybe_task) = || -> Result<(GitDatabase, GitOid, Option<usize>)> {
    // Short-circuit early if we already have the commit
    if let (Some(rev), Some(db)) = (self.git.precise(), &maybe_db) {
        if db.contains(rev) {
            debug!("Using existing Git source `{}`", self.git.repository());
            return Ok((maybe_db.unwrap(), rev, None));
        }
    }
    // Continue with fetching otherwise...
}();

// Bad: Using short-circuit when complete information is needed
// @any isn't sorted by version during discovery because we short-circuit
// when we find an interpreter that meets the request
// @latest needs to scan ALL Python interpreters to select the latest version
```

Consider the full requirements before deciding on a traversal strategy. When implementing algorithms that search or process collections:
1. Use short-circuit (like `.find()`) when the first match is sufficient
2. Use full traversal (like `.filter()` + `.max_by_key()`) when you need to examine all elements
3. Document your choice of strategy, especially when the behavior affects correctness

---

## Precise test pattern matching

<!-- source: zed-industries/zed | topic: Testing | language: Other | updated: 2025-06-09 -->

When identifying test patterns in code, use specific equality predicates (`#eq?`) instead of list inclusion predicates (`#any-of?`) when matching against a single value. This improves clarity and can avoid potential false positives in test detection.

For example, when matching the "each" method for parameterized tests:

```javascript
// Prefer this:
(#eq? @_property "each")

// Instead of this when there's only one value:
(#any-of? @_property "each")
```

This practice ensures more precise test pattern recognition, especially important for parameterized tests where accurate detection affects test execution and reporting.

---

## Use explicit permission notations

<!-- source: astral-sh/ruff | topic: Security | language: Rust | updated: 2025-06-09 -->

When setting file permissions through system calls like `chmod`, always use explicit octal notation (with the `0o` prefix) rather than decimal integers. Decimal integers in permission contexts can lead to unintended access rights, creating security vulnerabilities through incorrect file permissions.

For example, instead of:
```python
os.chmod("foo", 644)  # Incorrect - decimal integer
```

Use:
```python
os.chmod("foo", 0o644)  # Correct - explicit octal notation
```

The decimal value `644` is not equivalent to the octal value `0o644`, and this mismatch can lead to improper permission settings that may expose sensitive files to unauthorized access. Always verify permission values in security-sensitive operations.

---

## Consistent descriptive naming conventions

<!-- source: helix-editor/helix | topic: Naming Conventions | language: Markdown | updated: 2025-06-06 -->

Use consistent and descriptive naming conventions across the codebase:

1. Use kebab-case for configuration options and snake_case for internal modifiers
2. Prefer descriptive names over technical terms
3. Keep names concise while maintaining clarity
4. Use semantic prefixes to group related items

Example:
```toml
# Instead of:
[editor.bufferline]
behaviour = "hidden"
matches_couter_limit = 100

# Prefer:
[editor.bufferline]
show = "never"
max-matches = 100

# Group related commands with semantic prefixes:
:align-text-left
:align-text-center
:align-text-right
```

This convention ensures consistency, improves code readability, and makes configuration more intuitive for users. Descriptive names make the purpose immediately clear, while consistent casing helps distinguish between different types of identifiers.

---

## Pin GitHub actions

<!-- source: Homebrew/brew | topic: Security | language: Yaml | updated: 2025-06-06 -->

Always pin GitHub Actions to specific commit hashes rather than version tags (like @v4). Using version tags is a security vulnerability as the tag owner could change what commit the tag points to, potentially introducing malicious code into your workflow. This is a common supply chain security best practice.

Example:
```yaml
# INSECURE - Using version tag
steps:
  - name: Checkout Homebrew
    uses: actions/checkout@v4

# SECURE - Using commit hash
steps:
  - name: Checkout Homebrew
    uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4
```

Including the version as a comment after the hash helps with maintainability while preserving security.

---

## Document configuration formats explicitly

<!-- source: microsoft/playwright | topic: Configurations | language: Markdown | updated: 2025-06-06 -->

When documenting environment variables and configuration options, explicitly list all supported value formats rather than using vague descriptions. Use individual backticks around each supported value for clear formatting.

Avoid vague descriptions like "If a number is specified, it will also be used as the terminal width." Instead, be comprehensive and specific about what formats are accepted.

Example:
```markdown
| `PLAYWRIGHT_FORCE_TTY` | | Whether to produce output suitable for a live terminal. Supports `true`, `1`, `false`, `0`, `[WIDTH]`, and `[WIDTH]x[HEIGHT]`. `[WIDTH]` and `[WIDTH]x[HEIGHT]` specifies the TTY dimensions. | `true` when terminal is in TTY mode, `false` otherwise.
```

This approach helps users understand exactly what values they can provide and reduces configuration errors by eliminating ambiguity about supported formats.

---

## React transformation tool clarity

<!-- source: vitejs/vite | topic: React | language: Markdown | updated: 2025-06-06 -->

When working with React in Vite projects, be precise about which transformation tools (Babel, SWC, Oxc, esbuild) handle specific aspects of React code processing. Different plugins use different tool combinations for JSX/TSX transformation versus React fast-refresh, and these can vary between development and build environments.

For example, when documenting or selecting a React plugin:

```js
// Document precisely which tools handle which transformations
// @vitejs/plugin-react (without plugins)
//   - dev: Babel (fast-refresh) + esbuild/Oxc (JSX)
//   - build: esbuild/Oxc (JSX)

// @vitejs/plugin-react-swc (without plugins)
//   - dev: SWC (fast-refresh + JSX)
//   - build: esbuild/Oxc (JSX)

// @vitejs/plugin-react-oxc
//   - dev: Oxc (fast-refresh + JSX)
//   - build: Oxc (JSX)
```

This distinction is particularly important when migrating between plugins or when performance optimization is needed. Always verify compatibility with your project's requirements, especially when using custom Babel or SWC configurations.

---

## Explicit over implicit

<!-- source: zed-industries/zed | topic: API | language: Other | updated: 2025-06-06 -->

When designing APIs, prioritize explicit parameter identification over implicit context. APIs with clear, unambiguous parameters improve implementation, maintenance, and usage. Whenever a function could operate on multiple resources or have ambiguous behavior, include explicit parameters to clarify the intent.

Example of problematic API:
```
func language-server-workspace-configuration(language-server-id: string, worktree: borrow<worktree>) -> result<option<string>, string>;

// Ambiguous - which language server will receive this configuration?
func additional-language-server-workspace-configuration(language-server-id: string, worktree: borrow<worktree>) -> result<option<string>, string>;
```

Improved API:
```
func language-server-workspace-configuration(language-server-id: string, worktree: borrow<worktree>) -> result<option<string>, string>;

// Explicit - clearly identifies both the source and target language servers
func additional-language-server-workspace-configuration(
    source-language-server-id: string, 
    target-language-server-id: string,
    worktree: borrow<worktree>
) -> result<option<string>, string>;
```

Similarly, when designing RPC calls, ensure parameters are placed on the appropriate side of the interface. Parameters that can only be reasonably handled by the client (like UI focus control or selection) should not be included in server-side RPC parameters but should instead be handled in client-side logic or returned as part of the response.

---

## Structured environment configuration

<!-- source: Homebrew/brew | topic: Configurations | language: Ruby | updated: 2025-06-05 -->

Use structured environment variable handling with explicit validation instead of directly accessing ENV hash. Implement proper parsing for boolean values, default values, and type conversion. Consider making paths user-specific when creating temporary configurations.

For boolean environment variables, handle falsy values properly:

```ruby
# Instead of this:
if ENV["HOMEBREW_SOME_FLAG"].present?
  # Do something
end

# Do this:
if Homebrew::EnvConfig.some_flag?
  # Do something
end

# When implementing environment variable handlers:
def env_method_name(env, hash)
  if hash[:boolean]
    define_method(method_name) do
      env_value = ENV.fetch(env, nil)
      
      falsy_values = %w[false no off nil 0]
      if falsy_values.include?(env_value&.downcase)
        false
      else
        ENV[env].present?
      end
    end
  end
end
```

For configuration paths that may be shared across users, add user-specific identifiers:

```ruby
# Instead of this:
zdotdir = Pathname.new(HOMEBREW_TEMP/"brew-zsh-prompt")

# Do this:
zdotdir = Pathname.new(HOMEBREW_TEMP/"brew-zsh-prompt-#{Process.euid}")
```

This approach provides consistent interpretation of configuration values, reduces bugs from unexpected environment variable content, and prevents permission issues with shared configuration paths.

---

## Shell-specific input escaping

<!-- source: microsoft/vscode | topic: Security | language: TypeScript | updated: 2025-06-05 -->

When processing user input that will be used in shell commands, implement shell-specific escaping mechanisms to prevent command injection vulnerabilities. Different shells (bash, PowerShell, zsh, fish) have different escaping requirements that must be handled appropriately.

For example, instead of using a generic approach like:
```typescript
// Unsafe - generic character removal
const bannedChars = /[\`\$\|\&\>\~\#\!\^\*\;\<\"\']/g;
newPath = newPath.replace(bannedChars, '');
```

Implement shell-specific escaping:
```typescript
// Safe - proper shell-specific escaping
if (shellType === 'bash' || shellType === 'zsh') {
  // POSIX-compliant escaping for single quotes
  if (path.includes("'")) {
    path = path.replace(/'/g, "'\\''");
  }
} else if (shellType === 'fish') {
  // Fish uses backslash escaping
  if (path.includes("'")) {
    path = path.replace(/'/g, "\\'");
  }
} else if (shellType === 'powershell') {
  // PowerShell uses doubled single quotes
  if (path.includes("'")) {
    path = path.replace(/'/g, "''");
  }
}
```

This approach prevents security vulnerabilities by ensuring that user input cannot break out of string contexts to execute arbitrary commands.

---

## Prevent injection vulnerabilities

<!-- source: Homebrew/brew | topic: Security | language: Ruby | updated: 2025-06-03 -->

Always sanitize input data before using it in sensitive operations to prevent injection vulnerabilities. This applies to shell commands, file operations, and URL handling.

For shell commands:
```ruby
# VULNERABLE: Direct interpolation of variables into command
full_command = `#{HOMEBREW_BREW_FILE} #{brew_command} #{argument}`

# SECURE: Escape each argument properly
require 'shellwords'
full_command = [HOMEBREW_BREW_FILE, brew_command, argument].compact
                                                         .map { |arg| Shellwords.escape(arg) }
```

For file operations:
```ruby
# VULNERABLE: Using IO.read/Kernel.open with non-constant values
content = IO.read(filepath)

# SECURE: Use File.read instead
content = File.read(filepath)
```

For URL operations:
```ruby
# VULNERABLE: Using URI.open with non-constant values
response = URI.open(generated_url).read

# SECURE: Use URI().open instead
response = URI(generated_url).open.read
```

These patterns help prevent several classes of security vulnerabilities, including command injection, arbitrary file access, and server-side request forgery. Always assume input data could be malicious and handle it accordingly.

---

## Clear precise documentation

<!-- source: astral-sh/uv | topic: Documentation | language: Rust | updated: 2025-06-02 -->

Documentation should use direct, precise language that accurately describes components and their behavior. Maintain consistent grammatical structure throughout related documentation sections for improved readability.

For command-line options and parameters:
- Use direct statements rather than "Whether to..." phrasing when possible
- Clearly state both what an option does and the default behavior it modifies
- Be specific about the purpose and constraints of parameters

Example improvements:
```diff
- /// Whether to prefer uv-managed or system Python installations.
+ /// Disable use of uv-managed Python distributions.
+ ///
+ /// Instead, uv will search for a suitable Python installation on the system.

- /// Only print the final value
+ /// Only show the version
+ ///
+ /// By default, uv will show the project name before the version.

- /// The directory to store the Python installation in.
+ /// The directory Python installations are stored in.

- /// Upgrades will not remove lower installed patch versions.
+ /// During an upgrade, uv will not uninstall outdated patch versions.
```

For grammatical consistency, maintain the same tense within related sections, especially in enums where options are presented together. This improves scanning and comprehension of documentation.

---

## validate inputs early

<!-- source: microsoft/playwright | topic: Error Handling | language: TypeScript | updated: 2025-06-02 -->

Always validate function parameters and configuration options at the beginning of functions, providing specific and actionable error messages that guide users toward correct usage. This prevents downstream errors and improves developer experience.

Key practices:
- Check for required parameters and throw descriptive errors when missing
- Validate parameter types, ranges, and allowed values
- Use specific error messages that indicate what values are expected
- Perform validation before any side effects or expensive operations

Example:
```typescript
static validateNumber(value: string, options: { min?: number, max?: number }): string {
  if (/[^0-9]/.test(value))
    throw new InvalidArgumentError('Not a number.');
  const parsed = parseInt(value, 10);
  if (isNaN(parsed))
    throw new InvalidArgumentError('Not a number.');
  if (options.min !== undefined && parsed < options.min)
    throw new InvalidArgumentError(`Expected a number greater than ${options.min}.`);
  if (options.max !== undefined && parsed > options.max)
    throw new InvalidArgumentError(`Expected a number less than ${options.max}.`);
  return value;
}

// Validate enum values
if (!['begin', 'end'].includes(options.debug))
  throw new Error(`Unsupported debug mode "${options.debug}", must be one of "begin" or "end"`);

// Defensive checks for edge cases
if (!options.expectedText)
  throw new Error('expectedText is required for class validation');
```

This approach catches errors early, provides clear guidance to developers, and prevents cascading failures deeper in the system.

---

## Extract repeated logic

<!-- source: microsoft/playwright | topic: Code Style | language: TypeScript | updated: 2025-06-02 -->

When you find yourself writing similar code patterns multiple times, extract them into reusable methods, constants, or leverage existing helpers. This improves maintainability and reduces the chance of inconsistencies.

**Examples of what to extract:**

1. **Repeated code blocks** - Extract into shared methods:
```typescript
// Instead of duplicating enqueue logic:
for (let i = 0; i < repeatCount; ++i)
  this._frameQueue.push(this._lastFrameBuffer);

// Extract to:
private _enqueueFrames(count: number, buffer: Buffer) {
  for (let i = 0; i < count; ++i)
    this._frameQueue.push(buffer);
}
```

2. **Magic values used multiple times** - Use constants:
```typescript
// Instead of repeating colors:
const color = elements.length > 1 ? '#f6b26b7f' : '#6fa8dc7f';

// Use constants:
const HIGHLIGHT_COLOR_MULTIPLE = '#f6b26b7f';
const HIGHLIGHT_COLOR_SINGLE = '#6fa8dc7f';
```

3. **Leverage existing utilities** - Before writing new code, check if helpers already exist:
```typescript
// Instead of custom implementation, use existing helper:
const callLocation = wrapFunctionWithLocation((location: Location, ...args) => 
  this._modifier('skip', location, ...args)
);
```

4. **Avoid redundant computations** - Pass computed values instead of recomputing:
```typescript
// Instead of retrieving from map twice:
const data = this._dataByTestId.get(params.testId);
this._updateTest(data); // Pass the data directly
```

---

## Prevent unnecessary memory operations

<!-- source: ghostty-org/ghostty | topic: Performance Optimization | language: Other | updated: 2025-06-02 -->

Avoid redundant memory allocations and copies when simpler alternatives exist. This includes:

1. Use in-place comparison functions instead of allocating for string operations
2. Avoid duplicating data that is already owned or will be copied by the receiving function
3. Consider system-specific optimizations to minimize allocations

Example - Instead of:
```zig
const ext_lower = try std.ascii.allocLowerString(alloc, ext);
defer alloc.free(ext_lower);
if (std.mem.eql(u8, ext_lower, ".png")) {
```

Prefer:
```zig
if (std.ascii.eqlIgnoreCase(ext, ".png")) {
```

This guidance helps reduce memory pressure and improve performance by eliminating unnecessary allocations and copies. When working with data structures that handle their own memory management, verify if they copy inputs before performing manual duplication.

---

## Semantic name clarity

<!-- source: ghostty-org/ghostty | topic: Naming Conventions | language: Swift | updated: 2025-06-02 -->

Names should clearly and accurately reflect the purpose of variables, methods, and other identifiers. Follow these principles:

1. Use descriptive, specific names that convey exact purpose
2. For booleans, prefer positive phrasing with 'is' prefix when appropriate
3. Update names when functionality changes
4. Follow established platform conventions (e.g., AppKit notification naming patterns)

**Example 1:** Instead of:
```swift
var macosHidden: Bool
```
Use:
```swift
var isAppIconHiddenFromMacOS: Bool
```

**Example 2:** When a function's responsibility expands:
```swift
// Before: only hides elements
func hideCustomTabBarViews() {
    // hide some elements
}

// After: both hides and shows elements
func resetCustomTabBarViews() {
    // hide some elements
    // show other elements
}
```

**Example 3:** For notification naming, follow consistent patterns:
```swift
// Avoid inconsistent patterns
static let ghosttyToggleMaximize = Notification.Name(...)

// Follow "[Subject] [Event (past participle)]" pattern
static let ghosttyFullscreenDidToggle = Notification.Name(...)
```

---

## Configuration precision matters

<!-- source: vercel/turborepo | topic: Configurations | language: Json | updated: 2025-06-02 -->

Ensure configuration files are precise and stable to prevent unexpected build failures and runtime issues. This includes:

1. **Use correct syntax in configuration files**
   Validate JSON files for syntax errors like extra commas, which can cause cryptic error messages during builds.
   
   ```json
   // Incorrect
   {
     "$schema": "https://turborepo.com/schema.json",,
     "ui": "tui"
   }
   
   // Correct
   {
     "$schema": "https://turborepo.com/schema.json",
     "ui": "tui"
   }
   ```

2. **Specify exact versions for critical dependencies**
   Use exact versions instead of ranges (`^` or `~`) for dependencies when stability is critical, especially in test fixtures or shared packages.
   
   ```json
   // Less stable (allows minor updates)
   "dependencies": {
     "@types/d3-scale": "^4.0.2"
   }
   
   // More stable (locks exact version)
   "dependencies": {
     "@types/d3-scale": "4.0.2"
   }
   ```

3. **Explicitly specify package manager**
   Include the `packageManager` field in package.json to ensure consistent behavior across environments, especially when using version wildcards (`*`).
   
   ```json
   {
     "name": "monorepo",
     "packageManager": "pnpm@8.14.0",
     "dependencies": {
       "util": "*"
     }
   }
   ```

4. **Establish clear sources of truth**
   Define which configuration files are authoritative for specific settings. For example, make package.json's `engines` field the definitive source for Node.js version requirements.
   
   ```json
   "engines": {
     "node": "22.x"
   }
   ```

These practices reduce configuration drift, prevent unexpected behavior, and help maintain consistency across environments and team members.

---

## Respect connectivity state

<!-- source: astral-sh/uv | topic: Networking | language: Rust | updated: 2025-06-02 -->

Applications should gracefully handle different network connectivity states and provide appropriate feedback to users. Follow these guidelines:

1. **Check connectivity state before network operations** - Always verify if the application is in offline mode before attempting network requests
2. **Provide specific error messages** - When operations fail due to connectivity restrictions, include the exact reason in error messages
3. **Implement smart caching strategies** - Reduce network requests by checking local caches first
4. **Handle status codes appropriately** - Differentiate between retryable errors (like rate limits) and fatal errors with appropriate retry strategies

Example for offline handling:
```rust
if network_settings.connectivity.is_offline() {
    writeln!(
        printer.stderr(),
        "{}",
        format_args!(
            "{}{} Operation is not possible because network connectivity is disabled (i.e., with `--offline`)",
            // formatting details
        )
    )?;
    return Ok(ExitStatus::Failure);
}
```

Example for checking cache before network request:
```rust
// Check if we already have the resource locally before making a network request
if let (Some(rev), Some(db)) = (self.git.precise(), &maybe_db) {
    if db.contains(rev) {
        debug!("Using existing Git source `{}`", self.git.repository());
        return Ok((maybe_db.unwrap(), rev, None));
    }
}

// Only make network request if needed
// Handle different status codes appropriately
let decision = status_code_strategy.handle_status_code(status_code, index, capabilities);
```

---

## prevent null dereferences

<!-- source: hyprwm/Hyprland | topic: Null Handling | language: C++ | updated: 2025-06-01 -->

Always verify pointers are valid before dereferencing to prevent crashes and undefined behavior. This applies to regular pointers, weak pointers, and return values from C functions that may return null.

Use implicit bool conversion instead of explicit null comparisons for cleaner code:
```cpp
// Preferred
if (ptr) {
    ptr->doSomething();
}

// Avoid
if (ptr != nullptr) {
    ptr->doSomething();
}
```

For weak pointers, use the appropriate check method:
- Use `operator bool` or `.expired()` when you only need to test validity
- Use `.lock()` only when you need the actual shared pointer

Apply guard patterns with early returns to reduce nesting:
```cpp
if (!ptr)
    return;
    
ptr->doSomething();
```

Pay special attention to C function returns that may be null:
```cpp
const char* env = getenv("VAR_NAME");
if (!env)
    return defaultValue;
```

Critical areas requiring null checks include: pointer dereferences in event handlers, accessing monitor/window objects that may be destroyed, and any pointer obtained from external APIs or lookups.

---

## organize code properly

<!-- source: zen-browser/desktop | topic: Code Style | language: Other | updated: 2025-06-01 -->

Maintain clean code organization by separating concerns into appropriate classes and files. Extract large functions into smaller, focused methods, and avoid creating monolithic patches that become difficult to maintain.

Key principles:
- **Separate functionality into dedicated classes/files**: When adding new features, create separate classes or files rather than extending existing ones with unrelated functionality
- **Extract complex logic into named functions**: Replace inline patches and large code blocks with well-named functions that can be called from the appropriate context
- **Follow established patterns**: Use existing architectural patterns like extending `ZenDOMOperatedFeature` and moving constructor logic into `init()` methods

Example of good organization:
```javascript
// Instead of adding methods directly to an existing large class
class ZenSplitViewLinkDrop {
  constructor(zenViewSplitter) {
    this.#zenViewSplitter = zenViewSplitter;
  }
  
  init() {
    // Initialize functionality
  }
}

// Instead of large patches, extract to functions
gZenCompactModeManager.flashSidebarIfAllowed(aInstant);

// Instead of inline patches, use event listeners
popupElement.addEventListener('popupshowing', this.updateContextMenu.bind(this));
```

This approach improves maintainability, reduces conflicts, and makes code easier to understand and modify.

---

## Document non-obvious decisions

<!-- source: Homebrew/brew | topic: Documentation | language: Ruby | updated: 2025-05-30 -->

Always add clear comments explaining non-obvious code decisions such as magic numbers, arbitrary values, truncation limits, or special case handling. Convert magic numbers to named constants with explanatory comments when appropriate. This documentation helps future developers understand the reasoning behind code decisions and makes maintenance easier.

For magic numbers in code:
```ruby
# Read enough bytes to detect HTML doctype while limiting file I/O
if File.read(filepath, 100).strip.downcase.start_with?(html_doctype_prefix)
```

For truncation limits:
```ruby
# Maximum length of PR body is 65,536 characters so let's truncate release notes to half of that
body = github_release_data["body"].truncate(32_768)
```

For complex logic:
```ruby
# These formulae must build on Intel macOS because they're required for CLT installation
NEW_INTEL_MACOS_MUST_BUILD_FORMULAE = %w[pkg-config pkgconf].freeze
```

Code without explanatory comments creates a burden for maintainers, forcing them to reverse-engineer the original author's intent. Well-documented decisions reduce the cognitive load for future developers and decrease the likelihood of introducing bugs during modifications.

---

## Balance test performance considerations

<!-- source: astral-sh/uv | topic: Testing | language: Rust | updated: 2025-05-28 -->

When writing tests, consider both thoroughness and execution time. For operations with significant overhead (like Python installations, downloads, or filesystem operations), it's acceptable to consolidate multiple assertions into a single test.

```rust
// Instead of separate tests for each scenario:
#[test]
fn install_transparent_patch_upgrade_uv_venv() {
    // Setup context only once
    let context = TestContext::new_with_versions(&["3.13"]);

    // Test installing a lower patch version
    uv_snapshot!(context.filters(), context.python_install().arg("3.12.9"), /* ... */);

    // Create a virtual environment with same context
    uv_snapshot!(context.filters(), context.venv().arg("-p").arg("3.12"), /* ... */);
    
    // Test version verification with same context
    uv_snapshot!(context.filters(), context.run().arg("python").arg("--version"), /* ... */);
    
    // Test installing a higher patch version without recreating the environment
    uv_snapshot!(context.filters(), context.python_install().arg("3.12.10"), /* ... */);
}
```

When using snapshot testing, be conscious of brittleness. Try to make snapshots robust against implementation details while capturing essential behavior. For variable outputs, use focused filtering rather than replacing the entire expected output, or consider conditional snapshots for significantly different cases.

Prefer specific assertions (like `.assert().success()`) over empty snapshots when testing specific properties, as they provide better failure messages and are less likely to break on minor implementation changes.

---

## API consistency and decoupling

<!-- source: microsoft/playwright | topic: API | language: TSX | updated: 2025-05-28 -->

APIs should maintain consistent behavior and avoid tight coupling to implementation details or environmental dependencies. Don't make API methods conditionally available based on state, and avoid exposing filesystem paths or other environment-specific concerns in component interfaces.

Instead of conditional API availability:
```typescript
// Avoid: API becomes undefined based on conditions
{onCancel ? (
  <button onClick={onCancel}>Cancel</button>
) : null}
```

Use explicit state checks:
```typescript
// Prefer: Explicit state checking with consistent API
{conversation.isSending() ? (
  <button onClick={onCancel}>Cancel</button>
) : null}
```

Instead of tight coupling to filesystem:
```typescript
// Avoid: Component knows about rootDir and filesystem
const TestResultView = ({ test, result, rootDir }) => {
  // Component fetches files using rootDir
}
```

Decouple by pre-fetching data:
```typescript
// Prefer: Include data explicitly, making component portable
const TestResultView = ({ test, result, preloadedSources }) => {
  // Component works with provided data, no filesystem knowledge
}
```

This approach makes APIs more predictable, testable, and portable across different environments.

---

## Justify dependency changes

<!-- source: microsoft/playwright | topic: Configurations | language: Json | updated: 2025-05-28 -->

Always provide clear justification when modifying dependency configurations, including version updates, dependency types, or new additions. Consider the impact on stability, compatibility, and end users before making changes.

For version updates, avoid unnecessary churn by sticking with working versions unless there's a compelling reason to upgrade (security fixes, required features, bug fixes). For dependency types, choose between regular dependencies, devDependencies, and peerDependencies based on actual usage patterns and user compatibility needs.

Example considerations:
- Version updates: "Can we stick with the old version we already had to avoid unnecessary deps churn?"
- Dependency types: When adding peerDependencies, consider if users need flexibility with major versions vs. the complexity it introduces
- Compatibility: "If we hard-depend on Angular 18, we can cause problems to users who didn't migrate to Angular 18 yet"

Document the reasoning behind dependency configuration decisions to help future maintainers understand the trade-offs made.

---

## Redact URL credentials

<!-- source: astral-sh/uv | topic: Security | language: Rust | updated: 2025-05-26 -->

Always redact sensitive credentials in URLs before logging, displaying in error messages, or serializing to prevent accidental exposure of authentication information. Use dedicated wrapper types like `LogSafeUrl` that automatically handle credential redaction when displaying URLs:

```rust
// INSECURE: Directly logging a URL with potential credentials
log::debug!("Processing URL: {}", url);

// SECURE: Using a wrapper that handles credential redaction
log::debug!("Processing URL: {}", LogSafeUrl::from(url));
```

Be consistent in your approach to credential redaction:
- For debugging purposes, replace credentials with asterisks to indicate their presence (e.g., "****")
- For persistent storage like lockfiles, remove credentials entirely

Apply redaction as early as possible in the code path to minimize the risk that future changes might accidentally expose credentials. When implementing redaction logic, clearly document which approach is used in different contexts to maintain security throughout the application.

---

## prefer let-else patterns

<!-- source: helix-editor/helix | topic: Null Handling | language: Rust | updated: 2025-05-24 -->

When handling Option types that require early returns on None values, prefer the let-else pattern over verbose match statements or if-let constructs. This pattern improves code readability, reduces nesting, and makes the control flow more explicit.

The let-else pattern allows you to destructure an Option and immediately return or continue execution if the value is None, keeping the happy path at the main indentation level.

**Prefer this:**
```rust
let Some(context) = context else {
    return;
};

let Some(capabilities) = self.capabilities.get() else {
    return false;
};

let Some(last) = values_rev.peek() else {
    return;
};
```

**Instead of this:**
```rust
if context.is_none() {
    return;
}
let context = context.as_deref().expect("context has value");

match self.capabilities.get() {
    Some(capabilities) => capabilities,
    None => return false,
};

let last = match values_rev.peek() {
    Some(last) => last,
    None => return,
};
```

This pattern is particularly effective for guard clauses and input validation, where you want to handle the None case immediately and continue with the Some value. It reduces cognitive load by eliminating nested scopes and makes the error handling path explicit and concise.

---

## validate configuration values

<!-- source: prettier/prettier | topic: Configurations | language: JavaScript | updated: 2025-05-24 -->

Always validate configuration values and provide clear, actionable error messages when validation fails. Handle invalid values gracefully by either ignoring them or providing sensible defaults, and validate that configuration options are used in the correct context.

Key practices:
- Check for invalid values and ignore them rather than crashing: `if (tabWidth === 0) { /* ignore invalid value */ }`
- Validate configuration dependencies with clear error messages: `"--cache-strategy cannot be used without --cache"`
- Ensure configuration options are available in the expected context before using them
- Provide helpful suggestions when validation fails, such as suggesting similar valid options
- Handle edge cases like empty arrays or missing context gracefully: `if (ignoreFilePaths.length === 0 && !withNodeModules) { ignoreFilePaths = [undefined]; }`

This prevents runtime crashes, improves user experience, and makes configuration errors easier to debug and fix.

---

## Consistent Readability Rules

<!-- source: mermaid-js/mermaid | topic: Code Style | language: Other | updated: 2025-05-23 -->

{% raw %}
Code should be readable and consistent: avoid inline “magic” expressions, prefer named values/helpers, and use uniform style primitives.

Apply:
- Replace inline calculations with a named variable/helper when the expression is meaningful or potentially repeated:
  ```js
  const lastEdgeIndex = yy.getEdges().length - 1;
  $$ = $LINKSTYLE;
  yy.updateLink([lastEdgeIndex], $stylesOpt);
  ```
- Prefer consistent layout/style primitives over ad-hoc spacing classes (e.g., use flex `gap-*` instead of mixing `mr-*`, `mb-*`):
  ```vue
  <li v-for="{ iconUrl, featureName } in column" :key="featureName" class="flex gap-2 items-center">
    <img :src="iconUrl" :alt="featureName" class="inline-block h-5 w-5" />
    <span>{{ featureName }}</span>
  </li>
  ```
- Keep syntax and typing consistent (e.g., avoid unnecessary token quoting in grammars; align TS/ref typings across related structures).
- In scripts, use safe quoting/argument handling consistently (prefer arrays + `"${args[@]}"` for pass-through arguments).
- Remove unused grammar/lexer states or keep only what’s actively used; maintain logical rule ordering where it improves scanability.
{% endraw %}

---

## Declarative Vue Component Data

<!-- source: mermaid-js/mermaid | topic: Vue | language: Other | updated: 2025-05-23 -->

{% raw %}
In Vue SFCs, keep templates declarative and driven by explicit data.

**Rules**
1. **Put static/config data in `<script setup>`**: define typed constants/arrays in the script rather than building or embedding data via template expressions.
2. **Avoid `v-for` positional logic (`index`) for styling/behavior**: instead, add an explicit property on each item (e.g., `highlighted: true`) and base `:class`/conditional rendering on that.
3. **For interactive UI, keep template hints clear and aligned with behavior**: keyboard shortcut labels should be accurate and use appropriate semantics/markup (even if styling choices require minor CSS adjustments).

**Example (data-driven, no `index`)**
```vue
<script setup lang="ts">
import { ref } from 'vue';

interface Feature { iconUrl: string; featureName: string; }
interface Column {
  title: string;
  description: string;
  redirectUrl: string;
  highlighted?: boolean;
  features: Feature[];
}

const editorColumns: Column[] = [
  {
    title: 'Playground',
    description: 'Basic features, no login',
    redirectUrl: 'https://www.mermaidchart.com/play',
    features: [
      { iconUrl: '/icons/icon-public.svg', featureName: 'Diagram stored in URL' },
      { iconUrl: '/icons/icon-terminal.svg', featureName: 'Code editor' },
      { iconUrl: '/icons/icon-whiteboard.svg', featureName: 'Whiteboard' },
    ],
  },
  {
    title: 'Free',
    description: 'Advanced features, free account',
    redirectUrl: 'https://www.mermaidchart.com/app/sign-up',
    highlighted: true,
    features: [
      { iconUrl: '/icons/icon-folder.svg', featureName: 'Storage' },
      { iconUrl: '/icons/icon-terminal.svg', featureName: 'Code editor' },
    ],
  },
];

const isVisible = ref(false);
</script>

<template>
  <div v-if="isVisible" @click.self="isVisible = false">
    <div class="flex gap-4">
      <div
        v-for="col in editorColumns"
        :key="col.title"
        class="w-80 p-6 m-6 shadow-sm"
        :class="col.highlighted ? 'bg-white' : 'bg-[#dceef1]'"
      >
        <h3>{{ col.title }}</h3>
        <p>{{ col.description }}</p>
      </div>
    </div>
  </div>
</template>
```

This improves maintainability (template changes don’t silently break styling order) and makes behavior more testable and reviewable.
{% endraw %}

---

## Preserve API Contracts

<!-- source: mermaid-js/mermaid | topic: API | language: Other | updated: 2025-05-23 -->

When an endpoint or syntax is already used as a contract (e.g., chart grammar shared across features, or a stateful editor URL), avoid creating parallel interfaces or polluting the contract with unrelated concerns.

Apply this as:
- Prefer extending an existing syntax/API instead of adding a separate, parallel one (reduces duplication and client/parser divergence).
- If a URL encodes application state, keep the URL’s state-related parameters clean; don’t add marketing/tracking query params to the same URL the app uses to store/load state.

Example (clean stateful editor URL):
```ts
// Bad: pollutes a stateful URL used by the editor
const liveUrl =
  'https://mermaid.live/edit?utm_source=mermaid_js&utm_medium=editor_selection&utm_campaign=open_source';

// Good: keep only the contract URL; send analytics separately
const liveUrl = 'https://mermaid.live/edit';
```

---

## Bundle Static Assets

<!-- source: mermaid-js/mermaid | topic: Security | language: Other | updated: 2025-05-23 -->

Avoid directly linking UI/static assets (e.g., icons, images) to external domains. Keep them inside the repository and reference them via local paths so builds don’t depend on third-party availability, reduce tracking/privacy exposure, and minimize supply-chain risk.

Example (local assets instead of remote URLs):

```ts
// Instead of:
// iconUrl: 'https://static.mermaidchart.dev/assets/icon-public.svg'

import iconPublic from '@/assets/icons/icon-public.svg';
import iconTerminal from '@/assets/icons/icon-terminal.svg';
import iconWhiteboard from '@/assets/icons/icon-whiteboard.svg';

interface Feature {
  iconUrl: string;
  featureName: string;
}

const featureColumns = ref<Feature[][]>([
  [
    { iconUrl: iconPublic, featureName: 'Diagram stored in URL' },
    { iconUrl: iconTerminal, featureName: 'Code editor' },
    { iconUrl: iconWhiteboard, featureName: 'Whiteboard' },
  ],
]);
```

Apply this rule to all static resources used in the UI (icons, SVGs, logos, fonts) unless there is an explicit, approved exception with documented risk acceptance.

---

## Security terminology consistency

<!-- source: nrwl/nx | topic: Security | language: Markdown | updated: 2025-05-22 -->

Ensure consistent formatting and precise terminology when documenting security-related concepts, access controls, and system boundaries. Inconsistent or imprecise language in security documentation can lead to misunderstandings about permissions, access patterns, and security mechanisms.

Key practices:
- Use consistent formatting for technical security terms (e.g., `read-write` tokens, `read-only` tokens)
- Use precise and standardized terminology for system components (e.g., "shared global cache" rather than "shared primary cache")
- Clearly describe security boundaries and access patterns to prevent misconfigurations
- Maintain consistency in how security concepts are presented across documentation

Example:
```markdown
// Inconsistent - avoid
Read-write tokens allow access to the shared primary cache.

// Consistent - preferred  
The `read-write` tokens allow full write access to your shared global cache.
```

This practice is critical for security documentation where imprecise language can lead to incorrect implementations or security vulnerabilities.

---

## extract reusable workflow components

<!-- source: electron/electron | topic: CI/CD | language: Yaml | updated: 2025-05-22 -->

Avoid duplicating workflow steps across multiple CI/CD pipelines by extracting common functionality into reusable actions. This improves maintainability, reduces inconsistencies, and ensures proper cross-platform compatibility when needed.

When you find yourself copying similar workflow steps across multiple pipeline files, create a composite action instead. Pay special attention to cross-platform scenarios where caching or other features may require specific configuration.

Example of extracting a common dependency installation step:

```yaml
# Before: Duplicated across multiple workflows
- name: Get yarn cache directory path
  # ... repeated setup code

# After: Extract to .github/actions/install-dependencies/action.yml
- name: Install Dependencies
  uses: ./.github/actions/install-dependencies
  with:
    enable-cross-platform-cache: true
```

For cross-platform workflows, ensure proper configuration like `enableCrossOsArchive: true` when caching between different operating systems. This prevents cache restoration failures when artifacts are saved on one platform and restored on another.

---

## cache isolation boundaries

<!-- source: nrwl/nx | topic: Caching | language: Markdown | updated: 2025-05-22 -->

When documenting caching systems, clearly specify cache isolation boundaries and access scopes to prevent confusion about cache behavior. Distinguish between global shared caches and isolated caches, and explain how different access levels affect cache storage and retrieval patterns.

For example, when describing read-only access tokens:
```markdown
The `read-only` access tokens can only read from the global remote cache. Task results produced with this type of access token will be stored in an isolated remote cache accessible _only_ by that specific branch in a CI context, and cannot influence the global shared cache. The isolated remote cache is accessible to all machines or agents in the same CI execution, enabling cache sharing during distributed task execution.
```

This approach helps developers understand:
- Which cache layer their operations will affect
- The scope of cache accessibility (global vs isolated)
- How cache isolation prevents unauthorized cache pollution
- When cache sharing is still possible within defined boundaries

---

## Unicode homoglyph validation

<!-- source: microsoft/terminal | topic: Security | language: Txt | updated: 2025-05-22 -->

Validate Unicode characters and detect potential homoglyph attacks where visually similar characters from different scripts could be used maliciously. Avoid overly broad patterns that automatically allow non-ASCII characters without proper validation, as these can hide security vulnerabilities.

When processing text input or configuration patterns, be cautious of Unicode characters that could be used to bypass security measures. For example, a Cyrillic 'а' (U+0430) looks identical to Latin 'a' (U+0061) but could be used to create deceptive URLs, variable names, or bypass filtering rules.

Instead of using broad Unicode acceptance patterns like:
```
[a-zA-Z]*[ÀÁÂÃÄÅÆČÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝßàáâãäåæčçèéêëìíîïðñòóôõöøùúûüýÿ][a-zA-Z]{3}[a-zA-Z]*
```

Consider explicitly allowlisting known legitimate Unicode words or implementing homoglyph detection to identify suspicious character substitutions. This prevents cases where malicious characters like `é` instead of `,` could be hidden by overly permissive patterns, as such substitutions have been used in real-world attacks.

---

## Simplify complex code

<!-- source: bazelbuild/bazel | topic: Code Style | language: Java | updated: 2025-05-21 -->

Break down complex code structures into simpler, more readable forms to improve maintainability and reduce cognitive load. This involves several key practices:

**Extract duplicate code into helper methods:**
```java
// Instead of duplicating logic:
if (write) {
  new CommandBuilder()
      .setWorkingDir(env.getWorkspace())
      .addArg(modTidyValue.buildozer().getPathString())
      .addArg("-f")
      .addArg("-")
} else {
  new CommandBuilder()
      .setWorkingDir(env.getWorkspace())
      .addArg(modTidyValue.buildozer().getPathString())
      .addArg("-f")
      .addArg("-")
}

// Extract common construction:
private CommandBuilder createBaseBuilder() {
  return new CommandBuilder()
      .setWorkingDir(env.getWorkspace())
      .addArg(modTidyValue.buildozer().getPathString())
      .addArg("-f")
      .addArg("-");
}
```

**Use early returns to reduce nesting:**
```java
// Instead of nested conditions:
if (artifact instanceof DerivedArtifact) {
  return true;
} else if (artifact instanceof BasicActionInput || artifact instanceof VirtualActionInput) {
  return isOutputPath(artifact, outputRoot);
} else {
  return false;
}

// Use early returns:
if (artifact instanceof DerivedArtifact) {
  return true;
}
if (artifact instanceof BasicActionInput || artifact instanceof VirtualActionInput) {
  return isOutputPath(artifact, outputRoot);
}
return false;
```

**Prefer switch expressions over if-else chains:**
```java
// Instead of if-else:
Mode mode;
if (testCase.getStatus() == Status.PASSED) {
  mode = Mode.INFO;
} else {
  mode = Mode.ERROR;
}

// Use switch expression:
Mode mode = switch (testCase.getStatus()) {
  case PASSED -> Mode.INFO;
  default -> Mode.ERROR;
};
```

**Make implicit operations explicit for clarity:**
```java
// Instead of implicit this:
equals(platformValue)

// Be explicit:
this.equals(platformValue)
```

**Break large methods into focused smaller methods** when they handle multiple distinct responsibilities, and **extract string literals into constants** when they appear in multiple places or carry semantic meaning.

---

## Executor service lifecycle

<!-- source: bazelbuild/bazel | topic: Concurrency | language: Java | updated: 2025-05-21 -->

Properly manage executor service lifecycle to prevent resource leaks, deadlocks, and orphaned threads that can cause system inconsistencies.

Key practices:
1. **Use try-with-resources**: Always manage executors within try-with-resources blocks to ensure proper shutdown
2. **Avoid manual future cancellation**: Prefer structured concurrency patterns like `invokeAny()` over low-level `submit().get()` with manual cancellation
3. **Prevent orphaned threads**: Ensure worker threads are properly joined before allowing new operations to proceed
4. **Choose appropriate synchronization**: Use higher-level primitives like `Phaser` instead of combining multiple lower-level mechanisms

Example of proper executor management:
```java
try (var executor = Executors.newSingleThreadExecutor(threadFactory)) {
  // Submit tasks and get results within the try block
  var future = executor.submit(callable);
  return future.get(timeout, TimeUnit.SECONDS);
} // Executor automatically shuts down here
```

For cancellation scenarios, prefer structured approaches:
```java
// Instead of manual future cancellation
var future = executor.submit(task);
future.cancel(true);

// Use invokeAny for timeout/cancellation semantics
return executor.invokeAny(List.of(task), timeout, TimeUnit.SECONDS);
```

This prevents common issues like deadlocks when futures are never scheduled, ensures proper resource cleanup, and avoids race conditions from orphaned threads modifying shared state after new operations have begun.

---

## use descriptive names

<!-- source: helix-editor/helix | topic: Naming Conventions | language: Rust | updated: 2025-05-21 -->

Choose specific, purpose-revealing names that clearly communicate intent rather than generic, abbreviated, or ambiguous terms. Names should describe what something does or represents, not what it doesn't do.

**Examples of improvements:**
- Use `script_engine` instead of generic `engine` to clarify the file's purpose
- Use `workspace_diagnostics` instead of abbreviated `w_diagnostics` for clarity  
- Use `shush` instead of `noop` when the function has side effects (not truly a no-op)
- Describe functionality positively: "Only show filename" instead of "Don't expand filenames"
- Use `variables::expand()` instead of `expand_args()` to be clearer about what it operates on

**Apply this by:**
- Asking "Does this name clearly explain the purpose/behavior?" when naming functions, variables, modules, and types
- Avoiding generic terms like `engine`, `handler`, `manager` without qualifying context
- Preferring full words over abbreviations in public APIs and important identifiers
- Using positive descriptions that state what something does rather than what it doesn't do
- Ensuring names remain unambiguous even when used in different contexts

This principle improves code readability and reduces the cognitive load for developers trying to understand unfamiliar code.

---

## Use ASCII-only URLs

<!-- source: Homebrew/brew | topic: Networking | language: Ruby | updated: 2025-05-21 -->

URLs in code should exclusively use ASCII characters for maximum security and compatibility. This prevents potential security vulnerabilities like homograph attacks and ensures consistent behavior across systems.

For domain names with non-ASCII characters:
- Use Punycode encoding (e.g., `xn--` prefixed domains)

For path and query components:
- Use proper URL encoding for any non-ASCII characters

When validating URLs, include checks to ensure they contain only ASCII characters. Provide clear error messages to guide users toward the proper encoding.

Example:
```ruby
# Incorrect: URLs with non-ASCII characters
url = "https://🫠.sh/foo/bar"
url = "https://ßreｗ.sh/foo/bar"

# Correct: Use ASCII representations
url = "https://xn--sh-9ij.sh/foo/bar"  # Punycode for domain
url = "https://brew.sh/foo%E4%B8%AD%E6%96%87/bar"  # URL encoding for path

# For validation, use a regex to detect non-ASCII characters
ascii_pattern = /[^\p{ASCII}]+/
if url.match?(ascii_pattern)
  puts "Please use the ASCII (Punycode, URL encoded) version of #{url}."
end
```

---

## Configuration clarity standards

<!-- source: bazelbuild/bazel | topic: Configurations | language: Java | updated: 2025-05-20 -->

Configuration options should be designed with clarity, consistency, and user experience as primary concerns. This includes several key practices:

**Clear and specific help text**: Flag descriptions should explicitly explain their purpose and scope to avoid user confusion. For example, instead of generic descriptions, be specific about when and how the flag is used.

**Intuitive syntax with units**: When accepting time or quantity values, include units in the syntax for clarity. Use formats like `30s`, `5m`, `1h` instead of raw numbers, and document the expected format.

**Consistent behavioral patterns**: Maintain consistent conventions across similar flags. For example, if `0` disables functionality in some flags, apply this pattern consistently across related options. If `0` means "run immediately" for some flags, use the same convention for similar flags to reduce user confusion.

**Validation with helpful errors**: Prefer clear error messages over warnings for invalid configuration values. This reduces warning spam and makes it easier to evolve behavior later. Provide actionable feedback when validation fails.

**Proper option organization**: Place configuration options in appropriate option classes that reflect their actual usage and dependencies, rather than generic catch-all classes.

Example of good configuration design:
```java
@Option(
    name = "timeout",
    converter = DurationConverter.class,
    help = "Timeout for action execution. Use format like '30s', '5m', or '1h'. " +
           "Set to 0 to disable timeout.")
public Duration timeout;
```

This approach ensures configuration options are self-documenting, behave predictably, and provide a better developer experience.

---

## Documentation style and formatting

<!-- source: helix-editor/helix | topic: Code Style | language: Markdown | updated: 2025-05-19 -->

Maintain consistent documentation style by following these guidelines:

1. Use concise, descriptive language for configuration and feature descriptions
2. Format keyboard commands with `<kbd>` tags: `<kbd>i</kbd>`
3. Use **bold** for mode names and important terms
4. Use hyphens (-) instead of underscores (_) in parameter names and technical terms
5. Keep descriptions clear and to-the-point

Example:
```markdown
# Configuration
| Key            | Description                  | Default |
| -------------- | ---------------------------- | ------- |
| `auto-format`  | Enable auto-formatting      | `false` |

Press <kbd>i</kbd> to enter **Insert** mode.

---

## Measure performance impacts

<!-- source: prettier/prettier | topic: Performance Optimization | language: JavaScript | updated: 2025-05-18 -->

Always benchmark and measure actual performance impacts before making optimization decisions, rather than relying on assumptions. Performance characteristics can vary significantly across different runtimes, data sizes, and usage patterns.

When optimizing code:
- Conduct micro-benchmarks for critical paths to compare alternatives
- Consider runtime-specific performance characteristics (e.g., "Array#at is slow on Node.js v16 and v18")
- Measure real-world performance improvements and adjust expectations accordingly
- Balance trade-offs between code clarity and performance based on actual data

Example from codebase:
```javascript
// Micro benchmarking showed trim().length was faster than regex
// Choose based on measurement, not assumption
const keepTypeCast = text.slice(locEnd(previousComment), locStart(node)).trim().length === 0;
// vs
const keepTypeCast = !/\S/.test(text.slice(locEnd(previousComment), locStart(node)));
```

For performance-critical code, document the reasoning behind optimization choices and include performance test cases that can detect regressions. When performance improves significantly (e.g., 10x faster), update test expectations to catch future performance degradations.

---

## avoid version-specific documentation

<!-- source: helix-editor/helix | topic: CI/CD | language: Markdown | updated: 2025-05-17 -->

When writing build and deployment documentation, avoid hard-coding specific version numbers, toolchain assumptions, or environment-specific details that will become outdated or may not apply to all users. Instead, use generic language that describes the underlying requirement or constraint.

For example, instead of specifying exact versions like "Ubuntu 22.04" or "libc6 (>= 2.34)", explain the general compatibility concern: "The CI may use a libc version greater than what your Ubuntu/Debian/Mint version requires." Similarly, avoid assuming specific toolchain managers like rustup when providing build commands - not all users will have the same setup.

This approach ensures documentation remains accurate and useful over time, reduces maintenance burden, and provides better user experience across different development environments.

Example of brittle documentation:
```sh
# Assumes rustup is available
cargo +stable install --path helix-term --locked
```

Better approach:
```sh
# Works with any cargo installation
cargo install --path helix-term --locked
```

---

## Use realistic doc examples

<!-- source: helix-editor/helix | topic: Documentation | language: Markdown | updated: 2025-05-17 -->

Documentation should include concrete, realistic examples that demonstrate practical usage rather than abstract concepts. This helps readers better understand the functionality and improves documentation accessibility for all skill levels.

Examples should:
1. Demonstrate real-world use cases
2. Include full context when needed
3. Explain technical terms when used
4. Show practical applications

Good example:
```
# Explaining a git blame command
:echo %sh{git blame -L %{cursor_line},+1 %{buffer_name}}

# Explaining variables
Set a format string for `format` to customize the blame message. 
Variables are text placeholders wrapped in curly braces (`{variable}`).
```

Instead of just describing features abstractly, this approach shows actual usage patterns that readers can relate to and adapt for their needs. When technical terms are necessary, include brief explanations to make the documentation accessible to a wider audience.

---

## Ensure CI dependency reliability

<!-- source: astral-sh/ty | topic: CI/CD | language: Yaml | updated: 2025-05-15 -->

CI workflows should use the most current versions of dependencies and ensure all required tools are available. Avoid testing against potentially stale submodules or bundled dependencies by checking out the target repository directly. Use self-installing tools and hooks that handle their own installation to prevent failures due to missing dependencies.

For repository dependencies, checkout the actual target repository rather than a repo containing it as a submodule:

```yaml
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
  with:
    persist-credentials: false
    repository: astral-sh/ruff  # Target repo, not the repo with submodule
```

For tool dependencies, prefer pre-commit hooks or actions that handle installation automatically:

```yaml
- repo: https://github.com/astral-sh/uv-pre-commit  # Self-installing hook
```

This approach ensures CI tests run against the latest code and don't fail due to missing tools, improving reliability and reducing maintenance overhead.

---

## Ensure comprehensive test coverage

<!-- source: bazelbuild/bazel | topic: Testing | language: Java | updated: 2025-05-14 -->

When implementing new functionality or modifying existing code, always add corresponding tests that comprehensively cover the changes. This includes testing the main functionality, edge cases, error conditions, and different execution paths.

Key practices to follow:

1. **Add tests for new functionality**: Every new feature, method, or code path should have dedicated test coverage. As noted in one discussion: "The change affects the logic in RecursiveFileSystemTraversalFunction, I would still recommend adding a test case for that."

2. **Cover multiple scenarios**: Use parameterized tests or multiple test methods to cover different input combinations, configurations, and edge cases. Consider testing both positive and negative cases.

3. **Test different code paths**: When code has multiple execution branches (like different strategies or conditional logic), ensure each path is tested. For example: "Can you also parameterize these tests for `ctx.actions.write_file` and `ctx.actions.expand_template`?"

4. **Include edge cases and error conditions**: Don't just test the happy path. Test boundary conditions, invalid inputs, and error scenarios. As suggested: "Some more ideas for test cases: A regex with an alternation matching two different test strings, test strings containing metacharacters..."

5. **Verify transformations explicitly**: When testing data transformations or conversions, test both the input and output explicitly to ensure both halves of the operation work correctly.

Example of comprehensive test coverage:
```java
@Test
public void build_changedSourceDirectory_rebuildsTarget(@TestParameter Change change) {
  // Setup initial state
  setupInitialBuild();
  
  // Apply the change
  change.apply(getWorkspace().getRelative("pkg/dir"));
  
  // Verify the expected behavior
  buildTarget("//foo:a");
  assertContainsEvent(events.collector(), "Executing genrule //pkg:a");
}
```

This approach ensures that code changes are properly validated and reduces the risk of regressions in production.

---

## Use modern null-safe operators

<!-- source: microsoft/playwright | topic: Null Handling | language: TSX | updated: 2025-05-14 -->

Prefer optional chaining (`?.`) and nullish coalescing (`??`) operators over verbose null checks and ternary expressions. These modern JavaScript operators provide cleaner, more readable code while preventing runtime errors from null or undefined values.

Instead of explicit null checks:
```javascript
// Avoid
const annotations = item.testCase ? [...item.testCase.annotations, ...item.testCase.results.flatMap(r => r.annotations)] : [];

// Prefer
const annotations = item.testCase?.results[0] ? [...item.testCase.annotations, ...item.testCase.results[0].annotations] : [];
```

For array access and method calls, use optional chaining with nullish coalescing:
```javascript
// Avoid
annotations.push(...test.results[selectedResultIndex].annotations);

// Prefer  
annotations.push(...test.results[selectedResultIndex]?.annotations ?? []);
```

This approach reduces boilerplate code, improves readability, and provides built-in null safety without sacrificing functionality.

---

## Document code purposefully

<!-- source: vitejs/vite | topic: Documentation | language: TypeScript | updated: 2025-05-13 -->

High-quality code documentation improves maintainability and helps other developers understand your intentions. Follow these practices:

1. **Use appropriate JSDoc annotations** to indicate API visibility and status:
   ```typescript
   /** @internal */
   hostname: Hostname
   
   /**
    * @deprecated Use `createIdResolver` from `vite` instead.
    */
   ```

2. **Structure API documentation logically** by describing functionality first, then providing implementation details or deprecation notices:
   ```typescript
   /**
    * Create an internal resolver to be used in special scenarios, e.g.
    * optimizer & handling css `@imports`.
    *
    * This API is deprecated. It only works for the client and ssr
    * environments. The `aliasOnly` option is also not being used anymore.
    * Plugins should move to `createIdResolver(environment.config)` instead.
    */
   ```

3. **Add explanatory comments for non-obvious code decisions** to explain the "why" behind implementation choices:
   ```typescript
   // only limit to these extensions because:
   // - for the `@import`/`@use`s written in file loaded by `load` function,
   //   the `canonicalize` function of that `importer` is called first
   // - the `load` function of an importer is only called for the importer
   //   that returned a non-null result from its `canonicalize` function
   (resolved.endsWith('.css') || resolved.endsWith('.scss') || resolved.endsWith('.sass'))
   ```

4. **Keep documentation updated** when implementing changes, especially for deprecated features. Explicitly indicate migration paths and alternatives when deprecating functionality.

---

## consistent spacing grid

<!-- source: microsoft/playwright | topic: Code Style | language: Css | updated: 2025-05-12 -->

Use consistent spacing values that follow a standardized grid system, typically multiples of 4px or 8px, rather than arbitrary values. This ensures visual consistency across the UI and makes the design system more maintainable.

Avoid arbitrary spacing values like 2px, 3px, or 6px. Instead, stick to grid-based values:

```css
/* Avoid arbitrary values */
.status-passed {
  gap: 2px; /* ❌ */
}

.status-failed {
  gap: 3px; /* ❌ */
}

.container {
  gap: 6px; /* ❌ */
}

/* Use consistent grid values */
.status-passed,
.status-failed {
  gap: 4px; /* ✅ or 8px */
}

.container {
  gap: 8px; /* ✅ */
}
```

When spacing feels off visually, resist the temptation to use custom values for individual cases. Instead, evaluate whether the grid system needs adjustment or if the visual issue can be solved through other means like proper alignment or typography adjustments. This maintains design system integrity and prevents CSS from becoming inconsistent and hard to maintain.

---

## Safe URL/SVG Escaping

<!-- source: mermaid-js/mermaid | topic: Security | language: Markdown | updated: 2025-05-12 -->

When building URL-like strings that will be embedded into SVG attributes (e.g., `marker-end="url(...)"`), do not rely on upstream HTML escaping. Apply context-specific escaping/encoding for the exact attribute syntax, ensuring correct escaping order (notably escape backslashes first) and covering all unsafe characters—not just parentheses.

Example pattern:

```js
function escapeForSvgUrlAttribute(input) {
  // Escape order matters: backslash must be escaped before other replacements.
  return input
    .replace(/\\/g, '\\\\') // backslash first
    .replace(/['"\s]/g, encodeURIComponent) // also handle quotes/whitespace
    .replace(/[()]/g, (m) => '\\' + m); // e.g., parentheses
}

const url = `http://localhost:9000/flowchart.html?hi=${escapeForSvgUrlAttribute(s)}`;
markerEnd = `url(${url}#id)`;
```

Also ensure the stricter escaping is applied in the sensitive code path(s) (e.g., only the branch where the absolute marker URL is constructed), since that’s where malformed/incorrect `url(...)` expressions can break rendering and undermine safety assumptions.

---

## Document configuration clearly

<!-- source: zed-industries/zed | topic: Code Style | language: Json | updated: 2025-05-11 -->

When adding or modifying configuration parameters, especially in JSON settings files, ensure they are clearly documented with comments that explain:
1. The purpose of the parameter
2. The unit of measurement for numeric values
3. Whether the value is a default, minimum, or maximum
4. Any constraints or considerations

Use descriptive names rather than cryptic ones, and consider uncommenting default values to make them explicit to users. This improves maintainability and helps prevent confusion.

Example:
```json
"inline": {
  // Whether to show diagnostics inline or not
  "enabled": false,
  // The delay in milliseconds to show inline diagnostics after the
  // last buffer update.
  "delay_ms": 0,
  // The amount of padding between the end of the source line and the start
  // of the inline diagnostic in units of columns.
  "padding": 6
}
```

For context names, prefer clear, concise descriptors that convey meaning rather than listing all conditions explicitly:

```json
// Instead of:
"context": "Editor && showing_multiple_signature_help && !showing_completions"

// Prefer:
"context": "Editor && can_scroll_signature_help"
```

---

## prefer simple API designs

<!-- source: bazelbuild/bazel | topic: API | language: Java | updated: 2025-05-09 -->

Design APIs with simple, direct interfaces rather than complex parameter passing patterns or unnecessary indirection. Use appropriate parameter types (e.g., `PathFragment` instead of `String`, `ImmutableMap` instead of `BiFunction`) and avoid expanding API surface area when existing patterns can be reused.

**Key principles:**
- **Direct method calls over complex parameter passing**: Instead of plumbing arguments through multiple components, create direct API methods like `RunfilesSupport.withExecutableAndArgs()`
- **Appropriate parameter types**: Use domain-specific types (`PathFragment`) rather than generic ones (`String`) for better type safety
- **Minimize API expansion**: Reuse existing patterns and avoid adding new methods when current APIs can be extended consistently
- **Avoid complex function parameters**: Replace complex function types like `BiFunction<ImmutableMap<String, String>, String, ImmutableMap<String, String>>` with direct parameter passing

**Example:**
```java
// Avoid complex function parameters
public CppModuleMapAction(
    // ... other params
    BiFunction<ImmutableMap<String, String>, String, ImmutableMap<String, String>> modifyExecutionInfo) {

// Prefer direct parameter passing
public CppModuleMapAction(
    // ... other params  
    ImmutableMap<String, String> executionInfo) {
```

This approach makes APIs more predictable, easier to test, and reduces the cognitive load on API consumers while maintaining clear contracts between components.

---

## Document error handling limitations

<!-- source: electron/electron | topic: Error Handling | language: Markdown | updated: 2025-05-09 -->

When documenting error handling mechanisms, always provide complete context about how they work, including any limitations, edge cases, and alternative approaches. This prevents developers from making incorrect assumptions about behavior.

For example, when documenting warning suppression flags, clarify that suppression only affects default handlers while programmatic handling remains available:

```js
// Even with --no-warnings, apps can still handle warnings
process.on('warning', (warning) => {
  // Custom warning handling logic
});
```

Similarly, when documenting error handling behavior changes, ensure code examples accurately reflect the actual behavior and mention any known limitations:

```js
// Note: process.exit() may not synchronously crash utility processes
process.on('unhandledRejection', () => {
  process.exit(1); // May have timing issues in utility processes
});
```

This approach helps developers understand the full scope of error handling mechanisms and make informed implementation decisions.

---

## graceful process termination

<!-- source: microsoft/playwright | topic: Error Handling | language: JavaScript | updated: 2025-05-09 -->

Implement systematic cleanup mechanisms that handle process termination signals without generating excessive error output. Use a generic disposable pattern to manage resources that need cleanup during exit, SIGINT, or other termination scenarios.

Create a centralized list of disposables (child processes, contexts, file handles) that can be properly disposed of during shutdown. This prevents error flooding in the terminal and ensures resources are cleaned up systematically.

Example implementation:
```javascript
const disposables = [];

// Register disposables
disposables.push(() => child.kill());
disposables.push(() => context.dispose());

// Handle termination signals
process.on('SIGINT', () => {
  disposables.forEach(dispose => dispose());
  cleanup();
});

process.on('exit', () => {
  disposables.forEach(dispose => dispose());
});
```

This approach prevents the terminal flooding with error messages like "exited with code null, signal SIGINT" while ensuring all resources are properly cleaned up during process termination.

---

## Design ergonomic APIs

<!-- source: vercel/turborepo | topic: API | language: Rust | updated: 2025-05-07 -->

Create APIs that are both easy to use correctly and hard to use incorrectly. Focus on:

1. **Use pattern matching for safer error handling** instead of unwrapping values that might be null:

```rust
// Instead of:
let catalog_name = specifier.strip_prefix("catalog:").unwrap_or("default");

// Prefer:
if let Some(catalog_name) = specifier.strip_prefix("catalog:") {
    if let Some(catalogs) = &self.catalogs {
        // Use catalog_name directly
    }
}
```

2. **Accept more flexible parameter types** to improve API usability:

```rust
// Instead of:
fn token(mut self, value: String) -> Self {
    self.output.token = Some(value);
    self
}

// Prefer:
fn token(mut self, value: &str) -> Self {
    self.output.token = Some(value.into());
    self
}
```

3. **Make error states explicit** in return types to force proper error handling:

```rust
// Instead of:
Result<TurboJson, Error>

// Consider:
Result<Option<TurboJson>, Error>
```

4. **Use type-system features** like generics to create more flexible interfaces:

```rust
// Instead of:
fn view(app: &mut App<Box<dyn io::Write + Send>>, f: &mut Frame, rows: u16, cols: u16)

// Prefer:
fn view<W>(app: &mut App<W>, f: &mut Frame, rows: u16, cols: u16)
```

5. **Leverage serialization attributes** instead of manual implementations:

```rust
// Instead of manually implementing Serialize:
impl<'a> Serialize for RepositoryDetails<'a> { ... }

// Prefer using serde attributes:
#[serde(into)]
// With a From implementation to handle the conversion
```

These practices lead to APIs that are more intuitive, safer, and require less documentation to use properly.

---

## Configuration naming conventions

<!-- source: microsoft/vscode | topic: Configurations | language: Json | updated: 2025-05-07 -->

When adding new configuration settings, follow these naming conventions to maintain consistency and clarity:

1. **For related components**: Use a unified setting with resource scope instead of creating duplicate settings. For example, instead of having separate `typescript.maximumHoverLength` and `javascript.maximumHoverLength` settings, create a single `js/ts.hover.maximumLength` with resource scope:

```json
"js/ts.hover.maximumLength": {
  "type": "number",
  "default": 500,
  "description": "Controls the maximum length of hover content",
  "scope": "resource"
}
```

This approach allows for language-specific configuration while reducing configuration sprawl.

2. **For experimental features**: Clearly mark experimental settings in both their naming and metadata:
   - Prefix the setting name with `experimental` (e.g., `typescript.experimental.useTsgo` instead of `typescript.useTsgo`)
   - Include the "experimental" tag in the configuration metadata:

```json
"typescript.experimental.useTsgo": {
  "type": "boolean",
  "default": false,
  "description": "Controls whether to use TsGo for TypeScript processing",
  "tags": ["experimental"]
}
```

These conventions improve discoverability, communicate the stability status of features, and help maintain a cleaner configuration surface for users.

---

## Documentation clarity and formatting

<!-- source: ghostty-org/ghostty | topic: Documentation | language: Yaml | updated: 2025-05-06 -->

Ensure documentation is clear, precise, and consistently formatted. Key practices include:

1. **Be explicit and unambiguous** - Define terms that might be unclear and provide specific guidance:
   ```
   // Instead of:
   Please provide the minimum configuration needed.
   
   // Use:
   Please provide the minimum configuration needed to reproduce this issue. If you can still reproduce the issue with one of the lines removed, do not include that line.
   ```

2. **Use consistent naming and capitalization** for UI elements - Be precise about component names and locations:
   ```
   // Instead of:
   Screenshot of the terminal inspector's logged keystrokes
   
   // Use:
   Screenshot of logged keystrokes from the terminal inspector's "Keyboard" tab
   ```

3. **Format code examples properly** - Always wrap code and configuration examples in markdown code blocks with triple backticks, and include version information where relevant:
   ```markdown
   #### `tmux.conf` (tmux 3.5a)
   ```
   set -g default-terminal "tmux-256color"
   set-option -sa terminal-overrides ",xterm*:Tc"
   ```
   ```

4. **Provide platform-specific instructions** when behavior differs between environments:
   ```
   // Instead of:
   Provide any captured Ghostty logs.
   
   // Use:
   Provide any captured Ghostty logs. On Linux, this can be found by running `ghostty` from the command-line; on macOS, this can be found via [specific instructions].
   ```

5. **Use present tense** for examples and descriptions rather than future tense.

---

## Hierarchical configuration organization

<!-- source: zed-industries/zed | topic: Configurations | language: Json | updated: 2025-05-06 -->

Organize configuration settings hierarchically by grouping related settings under meaningful namespaces rather than creating numerous top-level settings. This improves maintainability, discoverability, and reduces configuration sprawl as your application grows.

When adding a new setting, consider:
1. Whether it belongs under an existing settings group
2. If similar settings should be grouped together in a new namespace
3. How the setting might evolve with additional related options in the future

For example, instead of:

```json
{
  "show_user_picture": true,
  "show_onboarding_banner": true,
  "show_status_bar": true
}
```

Prefer:

```json
{
  "titlebar": {
    "show_user_picture": true,
    "show_onboarding_banner": true
  },
  "status_bar": {
    "visible": true
  }
}
```

This approach keeps configuration maintainable as features expand and makes settings easier to locate and understand in context. It also facilitates future extensions without cluttering the root configuration space.

---

## Minimize allocations and syscalls

<!-- source: helix-editor/helix | topic: Performance Optimization | language: Rust | updated: 2025-05-04 -->

Optimize performance by minimizing unnecessary memory allocations and system calls. Key practices:

1. Avoid unnecessary String allocations:
```rust
// Instead of
let s = some_str.to_string();

// Use when possible
let s = some_str.into();
// Or
let s = Cow::Borrowed(some_str);
```

2. Pre-allocate collections when size is known:
```rust
// Instead of
let mut vec = Vec::new();
items.iter().for_each(|i| vec.push(i));

// Use
let mut vec = Vec::with_capacity(items.len());
items.iter().for_each(|i| vec.push(i));
```

3. Cache expensive system calls:
```rust
// Instead of
fn get_time() -> i64 {
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap()
        .as_secs() as i64
}

// Use
static TIME_CACHE: LazyLock<EditorTime> = LazyLock::new(|| {
    EditorTime {
        start: SystemTime::now(),
        since: Instant::now(),
    }
});
```

4. Return iterators instead of collecting into vectors when possible:
```rust
// Instead of
pub fn items(&self) -> Vec<Item> {
    self.items.iter().map(|i| i.clone()).collect()
}

// Use
pub fn items(&self) -> impl Iterator<Item = Item> + '_ {
    self.items.iter().cloned()
}
```

5. Avoid filesystem operations in hot paths:
```rust
// Instead of checking is_dir() repeatedly
if path.is_dir() { ... }

// Cache the information once
let is_dir = entry.file_type()
    .is_ok_and(|ft| ft.is_dir());
```

---

## Clear error recovery paths

<!-- source: Homebrew/brew | topic: Error Handling | language: Ruby | updated: 2025-05-03 -->

Implement error handling that provides both clear recovery paths for users and graceful degradation for the system. This includes:

1. Clear, actionable error messages that guide users to resolution
2. Graceful fallbacks when operations fail
3. Retry mechanisms for transient failures
4. Early returns to simplify error flows

Example:
```ruby
def handle_api_request
  return unless result.status.success?

  begin
    json = JSON.parse(result.stdout)
  rescue JSON::ParserError
    nil
  end
rescue AuthenticationError => e
  message = case credentials_type
  when :github_cli_token
    "Your GitHub CLI login session may be invalid.\n" \
    "Refresh it with: gh auth login"
  else
    "Token may be invalid or expired.\n" \
    "Check: https://github.com/settings/tokens"
  end
  raise UserError.new(message)
rescue TemporaryFailure => e
  @retry_count ||= 0
  raise if @retry_count >= MAX_RETRIES

  sleep_time = 2 ** @retry_count
  @retry_count += 1
  retry
end
```

This approach ensures systems degrade gracefully while providing users clear paths to resolve issues.

---

## prefer simple readable code

<!-- source: python-poetry/poetry | topic: Code Style | language: Python | updated: 2025-05-02 -->

Write code that prioritizes clarity and simplicity over cleverness. This improves maintainability and reduces cognitive load for other developers.

Key practices:
- Use positive conditionals instead of negative ones with empty blocks
- Extract inline conditions to named variables when they improve readability
- Avoid unnecessary complexity like functools.partial when simpler alternatives exist
- Inline variables that are only used once to reduce noise
- Use explicit parameter names for boolean arguments
- Keep methods concise and focused on a single responsibility
- Use modern Python idioms like pathlib's `/` operator and `or` for conditional assignment

Example of improvements:
```python
# Instead of negative conditional with empty block
if not condition:
    pass
else:
    do_something()

# Prefer positive conditional
if condition:
    do_something()

# Instead of inline complex condition
if not username and not password:
    return None

# Extract to named variable for clarity  
has_credentials = username or password
if not has_credentials:
    return None

# Instead of nameless boolean parameter
return self._handle_install(True)

# Use explicit parameter name
return self._handle_install(with_synchronization=True)
```

The goal is code that can be understood at a glance without requiring mental gymnastics to parse complex logic or unclear intentions.

---

## Propagate errors with context

<!-- source: vercel/turborepo | topic: Error Handling | language: Rust | updated: 2025-05-01 -->

Properly propagate errors to callers with sufficient context rather than handling them prematurely or hiding them. Let the caller decide how to handle errors when they have the appropriate context.

**Do:**
- Use the `?` operator to bubble up errors to callers
- Add context to errors when propagating them
- Use custom error types with `#[from]` for clean error conversion
- Include specific details in error messages that help users understand the issue

```rust
// Good: Propagate error with context
pub async fn run(base: CommandBase) -> Result<(), Error> {
    match info::run(base).await {
        Ok(()) => Ok(()),
        Err(e) => Err(Error::Info(e)) // With #[from] annotation on Error::Info
    }
}

// Good: Preserve error details
let exe_path = std::env::current_exe().map_or_else(
    |e| format!("Cannot determine current binary: {e}"),
    |p| p.display().to_string()
);

// Good: Use methods that include context in errors
preferences_file.ensure_dir()?; // Path information included in error
```

**Don't:**
- Use lossy conversions that cause silent failures
- Handle errors locally when the caller needs to make decisions
- Use generic error messages that hide important details
- Use `.unwrap()` or `.expect()` in production code paths unless failure is truly impossible

```rust
// Bad: Lossy conversion causing silent failures
let stdout = String::from_utf8_lossy(&stdout);

// Bad: Using unwrap which hides error context
let anchored_to_turbo_root_file_path = self
    .reanchor_path_from_git_root_to_turbo_root(turbo_root, path)
    .unwrap();
```

Only handle errors locally when you have sufficient context to make the right decision; otherwise, propagate them with as much information as possible.

---

## Explicit version requirements

<!-- source: vitejs/vite | topic: Configurations | language: JavaScript | updated: 2025-05-01 -->

Always specify explicit Node.js version requirements in configuration files to ensure compatibility with language features and APIs. When updating supported versions, verify feature compatibility and document reasoning behind version constraints.

For example, when using ESM modules with require:
```js
// In eslint.config.js or other config files
settings: {
  node: {
    // Specify exact version ranges that support needed features
    version: '^20.19.0 || ^22.12.0+', // Required for require(ESM) support
  },
}
```

When changing version requirements, consider:
1. Feature support across different versions (like ESM support)
2. Breaking changes that might affect existing functionality
3. Development environment consistency across the team

Explicitly defined version requirements help prevent unexpected lint errors, runtime issues, and improve developer experience by documenting version-specific feature availability.

---

## Eliminate code duplication

<!-- source: vercel/turborepo | topic: Code Style | language: Rust | updated: 2025-04-30 -->

Avoid duplicating logic, patterns, or data across the codebase. When similar code appears in multiple places, extract it into reusable functions or methods.

Examples:

1. Extract duplicated logic to shared functions:
```rust
// Instead of this:
let turbo_json_path = self.repo_root.join_component(CONFIG_FILE);
let turbo_jsonc_path = self.repo_root.join_component(CONFIG_FILE_JSONC);

let turbo_json_exists = turbo_json_path.exists();
let turbo_jsonc_exists = turbo_jsonc_path.exists();

// Extract to a helper function:
fn root_turbo_json_path(repo_root: &AbsoluteSystemPath) -> (AbsoluteSystemPathBuf, bool) {
    // Implementation that can be reused
}
```

2. Remove redundant initialization:
```rust
// Instead of:
enabled: remote_cache_opts.enabled,
no_update_notifier: None, // Remote cache options don't include this
..Self::default()  // This already handles no_update_notifier

// Just use:
enabled: remote_cache_opts.enabled,
..Self::default()
```

3. Prefer borrowing over cloning when possible:
```rust
// Instead of:
let repo_root = self.repo_root.clone();

// Use borrowing:
let repo_root = &self.repo_root;
```

4. Break large complex methods into smaller ones with clear responsibilities:
```rust
// Instead of embedding this logic in a larger function:
let conflict = {
    let own_invalidator = get_invalidator();
    let mut authorative_write_map = self.authorative_write_map.lock().unwrap();
    // ... 30+ lines of conflict resolution logic
};

// Extract to a dedicated method:
fn check_write_conflict(&self, path: &Path) -> Result<(), Error> {
    // Extracted conflict resolution logic
}
```

Following these practices improves maintainability, reduces the chances of inconsistencies, and makes the codebase easier to test and understand.

---

## Ensure comprehensive test coverage

<!-- source: electron/electron | topic: Testing | language: TypeScript | updated: 2025-04-29 -->

Always verify that tests cover all relevant scenarios, edge cases, and conditions rather than just the happy path. When reviewing or writing tests, actively look for missing test cases and suggest additional coverage.

Key areas to examine:
- **Edge cases and boundary conditions**: Test both positive and negative values, empty/null inputs, and limit cases
- **Platform-specific behavior**: Ensure tests cover different operating systems when functionality varies
- **Error conditions**: Test failure scenarios, non-zero exit codes, and exception handling  
- **Security-critical features**: Comprehensive testing is essential for security features before stable release
- **Different input types**: Test various URL types, data formats, and configuration options

Example from the discussions:
```typescript
// Instead of just testing the basic case
it('window opened with innerWidth option has the same innerWidth', async () => {
  // ... basic test
});

// Also test against related functionality
it('should also test against win.getContentSize()', async () => {
  // ... additional coverage
});

// And test edge cases
it('emits the resize event for single-pixel size changes', async () => {
  const [width, height] = w.getSize();
  const size = [width + 1, height - 1]; // Test both + and - changes
});
```

When you encounter a test that seems to work "incidentally" or only covers one scenario, ask: "What other conditions should this handle?" and "Are we missing any important edge cases?"

---

## Environment-aware configuration testing

<!-- source: bazelbuild/bazel | topic: Configurations | language: Shell | updated: 2025-04-29 -->

When writing tests for configuration-dependent functionality, implement environment detection and conditional logic to handle platform-specific differences. Tests should detect system capabilities and adjust expectations accordingly rather than assuming uniform behavior across all environments.

Key practices:
- Use capability detection before testing features that may not be universally supported
- Implement platform-specific path handling and formatting
- Adjust test expectations based on detected environment characteristics

Example from cross-platform path handling:
```bash
if is_windows; then
  expected_path=$(echo "$bazelrc" | sed 's/^C:/c:/; s/\//\\\\/g')
else
  expected_path="$bazelrc"
fi
expect_log "source: \"$expected_path\""
```

Example from compiler feature detection:
```bash
# Check if __builtin_FILE is supported and skip test if not supported
if ! compiler_supports_builtin_file; then
  echo "Skipping test: __builtin_FILE not supported"
  return
fi
```

This approach ensures tests are robust across different execution environments while maintaining meaningful validation of configuration behavior.

---

## Cache sharing strategy

<!-- source: astral-sh/uv | topic: Caching | language: Dockerfile | updated: 2025-04-29 -->

When implementing caching in build systems, carefully configure cache sharing behavior based on your concurrency requirements. Improper sharing settings can lead to build failures when multiple processes attempt to access the same cache simultaneously.

For Docker BuildKit cache mounts:
- Use `sharing=shared` (default) for caches with internal locking mechanisms or read-only access patterns
- Use `sharing=locked` when cache contents cannot handle concurrent writers
- Use `sharing=private` for isolated per-build caches that don't benefit from sharing
- Consider using tmpfs mounts to exclude directories containing temporary or easily regenerated data

Example of proper cache configuration:
```dockerfile
RUN \
  # Global cache that safely handles concurrent access
  --mount=type=cache,target=/var/lib/apt/lists,type=cache,sharing=shared \
  # Cache that needs exclusive access to prevent corruption
  --mount=type=cache,target="/root/.cache/rustup",id="rustup-toolchain",sharing=locked \
  # Project-specific build cache with isolated ID to prevent unintended sharing
  --mount=type=cache,target="target/",id="cargo-target-${APP_NAME}-${TARGETPLATFORM}",sharing=locked \
  # Exclude temporary directories from caching with tmpfs
  --mount=type=tmpfs,target="${CARGO_HOME}/registry/src" \
  --mount=type=tmpfs,target="${CARGO_HOME}/git/checkouts" \
  cargo build --release
```

Always consider the concurrency patterns of your build environment. Remember that caches with the same ID are shared across different builds, which can cause unexpected interactions between unrelated projects.

---

## Optimize docker build caching

<!-- source: astral-sh/uv | topic: CI/CD | language: Dockerfile | updated: 2025-04-29 -->

Leverage Docker BuildKit's cache and bind mount capabilities to dramatically improve CI build times and reduce image sizes. Instead of copying source files into intermediate layers, use bind mounts to provide build context and cache mounts for package managers and build artifacts.

**Why this matters:**
- Prevents bloating Docker layer cache with source files and build artifacts
- Significantly reduces build times in CI/CD pipelines
- Makes builds more consistent and reliable

**Implementation example:**
```dockerfile
# Use cache mounts for package managers
RUN \
  --mount=target=/var/lib/apt/lists,type=cache,sharing=locked \
  --mount=target=/var/cache/apt,type=cache,sharing=locked \
  <<HEREDOC
    apt update && apt install -y --no-install-recommends \
      build-essential \
      curl
HEREDOC

# Use bind mounts for source files and cache mounts for build artifacts
RUN \
  --mount=type=bind,source=src,target=src \
  --mount=type=bind,source=package.json,target=package.json \
  --mount=type=cache,target=node_modules \
  npm install && npm run build
```

Make sure your CI environment supports BuildKit (Docker 18.09+) and enable BuildKit features with `DOCKER_BUILDKIT=1`.

---

## Maintain consistent naming

<!-- source: zed-industries/zed | topic: Naming Conventions | language: Other | updated: 2025-04-28 -->

{% raw %}
Ensure naming follows consistent patterns throughout the codebase in both style and structure:

1. Use agreed-upon case style for identifiers (e.g., snake_case for functions):
```diff
- {{# if (hasTool 'grep') }}
+ {{# if (has_tool 'grep') }}
```

2. Maintain consistent ordering in hierarchical names, with namespaces coming first:
```diff
- export additional-language-server-workspace-configuration: func(...)
+ export language-server-additional-workspace-configuration: func(...)
```

3. For selectors and hierarchical identifiers, order components from less specific to more specific:
```diff
- (emphasis) @markup.emphasis
+ (emphasis) @emphasis.markup
```

This consistency improves code readability, makes the codebase more predictable, and reduces cognitive load when writing or reviewing code.
{% endraw %}

---

## Maintain style consistency

<!-- source: zed-industries/zed | topic: Code Style | language: Other | updated: 2025-04-27 -->

Ensure consistent styling is maintained across related elements in the codebase. This applies to:

1. **Visual assets**: Icons and images should match the established dimensions and styling of existing assets.
   ```
   // Example: All AI lab icons should be 16x16px
   ```

2. **Related file types**: When modifying style rules in one file, apply corresponding changes to related files of similar types.
   ```
   // When changing highlights in javascript/highlights.scm:
   (regex_flags) @keyword.operator.regex
   
   // Also update in typescript/highlights.scm and tsx/highlights.scm
   ```

3. **Semantic naming**: Use naming conventions that are logically consistent and avoid contradictory terminology. Ensure naming choices align with the conceptual understanding of the elements they represent.

Maintaining consistency improves readability, reduces confusion, and creates a more professional codebase that's easier to maintain over time.

---

## Avoid unwrap on nullables

<!-- source: alacritty/alacritty | topic: Null Handling | language: Rust | updated: 2025-04-26 -->

Never use `unwrap()` on nullable values that could reasonably be None, as this can cause crashes that are harder for users to work around than bugs. Instead, provide graceful fallbacks or proper error handling.

The principle is: "We shouldn't crash here under any circumstances" and "Bugs would be easier to work around for users than crashes."

**Preferred patterns:**

```rust
// Bad - crashes on None
let country_code = locale.countryCode().unwrap();

// Good - graceful fallback
if let Some(country_code) = locale.countryCode() {
    format!("{}_{}.UTF-8", language_code, country_code)
} else {
    // Fall back to en_US in case the country code is not available.
    "en_US.UTF-8".to_string()
}

// Good - using map_or for cleaner handling
match self.hint.mouse {
    None => MouseButton::Left,
    Some(c) => c.button.0,
}
// Better as:
self.hint.mouse.map_or(MouseButton::Left, |c| c.button.0)

// Bad - empty string treated as valid due to unwrap_or(0)
let codepoint = text.chars().next().map(u32::from).unwrap_or(0);

// Good - explicit empty check
let codepoint = match text.chars().next() {
    Some(c) => u32::from(c),
    None => return false, // Handle empty case explicitly
};
```

Use `if let Some()`, `map_or()`, or explicit match statements instead of `unwrap()` to handle nullable values safely.

---

## refactor complex conditions

<!-- source: prettier/prettier | topic: Code Style | language: JavaScript | updated: 2025-04-25 -->

Break down complex inline conditions and nested logic into separate, well-named functions or simpler expressions to improve code readability and maintainability.

Complex boolean expressions, deeply nested conditionals, and inline logic with multiple concerns should be extracted into helper functions or simplified using more readable patterns. This makes the code easier to understand, test, and modify.

Examples of improvements:

```javascript
// Before: Complex inline condition
return value !== "" && 
  !(value === "\n" && 
    typeof adjacentNodes === "object" && 
    (adjacentNodes?.previous?.kind === "cj-letter" || 
     adjacentNodes?.next?.kind === "cj-letter") && 
    !isSentenceUseCJDividingSpace(path))
  ? isBreakable ? line : " " 
  : isBreakable ? softline : "";

// After: Extracted helper function
if (value !== "" && canBeConvertedToSpace(path, value, adjacentNodes)) {
  return isBreakable ? line : " ";
}
return isBreakable ? softline : "";

function canBeConvertedToSpace(path, value, adjacentNodes) {
  // Clear, focused logic here
}
```

```javascript
// Before: Complex array operations
if (commaGroup.groups.length > 1) {
  for (const group of commaGroup.groups) {
    if (group.value && typeof group.value === "string" && group.value.includes("#{")) {
      // complex logic
      break;
    }
  }
}

// After: Simplified with array methods
if (commaGroup.groups.some(group => 
  typeof group.value === "string" && group.value.includes("#{"))) {
  // simplified logic
}
```

This approach reduces cognitive load, makes code self-documenting through function names, and enables better testing of individual logical components.

---

## prefer efficient algorithms

<!-- source: prettier/prettier | topic: Algorithms | language: JavaScript | updated: 2025-04-25 -->

Choose more efficient algorithmic approaches by leveraging built-in methods and APIs instead of implementing manual solutions. This includes using iterator methods over manual loops, direct comparisons over complex operations, and existing path traversal APIs over custom implementations.

Key optimizations to apply:
- Use iterator methods like `.next().done` instead of manual for-loops with early returns
- Prefer direct comparisons (`a.offset - b.offset`) over complex multi-step operations
- Leverage existing APIs like `path.siblings`, `path.next`, `path.index` instead of manual array traversal with `findIndex()` and `find()`
- Consider O(1) operations and appropriate data structures for performance-critical code

Example transformations:
```javascript
// Instead of manual loop with early return
function isLeaf(node, options) {
  for (const _ of getChildren(node, options)) {
    return false;
  }
  return true;
}

// Use iterator method
function isLeaf(node, options) {
  return getChildren(node, options).next().done;
}

// Instead of complex string operations
if (!options.originalText.slice(locEnd(iNode), locStart(iNextNode)).includes(" "))

// Use direct comparison
if (locEnd(iNode) === locStart(iNextNode))

// Instead of manual array traversal
const elementIdx = elements.findIndex((v) => v == elementNode);
const nextNode = elements.find((e, i) => i > elementIdx && e !== null);

// Use path APIs
// path.siblings, path.next, path.index should be used
```

This approach reduces computational complexity, improves readability, and leverages well-tested library functions.

---

## Environment variable safety

<!-- source: Homebrew/brew | topic: Configurations | language: Shell | updated: 2025-04-25 -->

When configuring environment variables, especially those related to paths, implement these safety practices:

1. Validate path accessibility before use to ensure the environment is properly configured
2. Use dynamic evaluation in shell configurations instead of static values
3. Always add directories (not executables) to PATH variables
4. Consider shell compatibility issues for different environments

```sh
# Validate paths before setting environment variables
if [[ -r "/var/tmp" && -w "/var/tmp" ]]
then
  TEMP_DIR="/var/tmp"
else
  TEMP_DIR="/tmp"
fi

# Use dynamic evaluation in shell config files
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.bashrc
# NOT: /opt/homebrew/bin/brew shellenv >> ~/.bashrc

# Add directories (not executables) to PATH
export PATH="/opt/homebrew/bin:$PATH"  # Correct
# NOT: export PATH="/opt/homebrew/bin/brew:$PATH"  # Incorrect

# Handle unset variables in strict mode shells
export PATH="${HOMEBREW_PREFIX}/bin:${HOMEBREW_PREFIX}/sbin${PATH+:$PATH}";
```

---

## Encapsulate implementation details

<!-- source: ghostty-org/ghostty | topic: API | language: Other | updated: 2025-04-23 -->

When designing APIs, create appropriate abstractions that hide platform-specific or low-level implementation details from consuming code. Avoid exposing raw interfaces outside their designated modules and minimize unnecessary dependencies.

**Good Practice:**
- Isolate platform-specific code in dedicated modules
- Use abstractions that hide underlying implementation complexity
- Only bind to resources that are actually used
- Consider direct imports for external dependencies when appropriate

For example, instead of binding to an unused protocol:

```zig
// AVOID: Unnecessary binding that adds dependencies
if (registryBind(
    xdg.WmDialogV1,
    registry,
    global,
)) |wm_dialog| {
    context.xdg_wm_dialog = wm_dialog;
    return;
}
```

Instead, simply check if the protocol is available without binding:

```zig
// BETTER: Just compare against the name and set a flag
if (isProtocolSupported(registry, global, "xdg_wm_dialog")) {
    context.has_wm_dialog_support = true;
    return;
}
```

Similarly, avoid using raw C interfaces outside their dedicated modules. Create proper abstractions that isolate platform-specific details, making the codebase more maintainable and portable.

---

## Sanitize debug output

<!-- source: ghostty-org/ghostty | topic: Security | language: Python | updated: 2025-04-23 -->

Never print or log sensitive information such as tokens, passwords, or secrets that might be present in environment variables or configuration. When debugging with environment variables, always sanitize the output by filtering out sensitive keys.

Instead of:
```python
print(*os.environ)
# or
print("token_start", repr(os.environ["GITHUB_TOKEN"][:10]))
```

Use sanitized output:
```python
print("Environment variables (sanitized):")
print({k: v for k, v in os.environ.items() if "TOKEN" not in k and "PASSWORD" not in k and "SECRET" not in k})
```

This prevents accidental exposure of credentials in logs, console output, or error reports that could lead to security breaches if captured by unauthorized parties.

---

## Clean configuration organization

<!-- source: vitejs/vite | topic: Configurations | language: Json | updated: 2025-04-18 -->

Organize configuration settings logically and avoid redundancy in project configuration files. Group related options into appropriate sections, eliminate duplicated settings (especially those already provided by extended configurations), and document non-obvious choices with explanatory comments.

TypeScript configurations should:
- Place options in semantically appropriate sections (e.g., linting options in "Linting" section)
- Avoid repeating options already provided by extended configurations
- Remove options that are already implied by other settings

```diff
// In tsconfig.json
{
  "extends": "@tsconfig/ember",
  "compilerOptions": {
    /* Bundler mode */
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
-   "isolatedModules": true,
+   "verbatimModuleSyntax": true, // In "Linting" section below
    
    /* Linting */
    "strict": true,
+   "verbatimModuleSyntax": true, // Moved from "Bundler mode"
-   "strictBuiltinIteratorReturn": true, // Redundant with "strict: true"
  }
}
```

For new plugins or packages, prefer modern module configurations:
```json
{
  "name": "@vitejs/plugin-example",
  "type": "module",  // Prefer ESM for new packages
  "files": ["dist"]
}
```

This approach improves maintainability and helps onboard new developers by making configuration intent clearer while reducing conflicting settings.

---

## Leverage native tooling

<!-- source: vitejs/vite | topic: Performance Optimization | language: Markdown | updated: 2025-04-18 -->

Prioritize native or Rust-based implementations of build tools over their JavaScript counterparts to significantly improve performance in both development and build phases. Tools like Rolldown (replacing Rollup and esbuild) can reduce build times and provide a more consistent experience between development and production environments.

When developing plugins, utilize native performance features like hook filters to reduce overhead:

```js
// Example: Using hook filters in Rolldown plugins for better performance
const plugin = {
  name: 'my-performance-plugin',
  resolveId: {
    filter: /\.custom$/, // Only process specific files
    handler(source, importer) {
      // Handler only called for matching files, reducing JS-Rust communication overhead
      return this.resolve(source, importer);
    }
  }
}
```

For large applications, consider replacing multiple JavaScript-based tools with their native equivalents to create a more streamlined, performant pipeline. This approach reduces both build times and runtime overhead while maintaining compatibility with the existing ecosystem.

---

## Handle errors explicitly

<!-- source: microsoft/playwright | topic: Error Handling | language: TSX | updated: 2025-04-18 -->

Always provide explicit error handling instead of allowing silent failures or blank screens. Any place where an error can occur but is not handled explicitly is a bug. When errors occur, communicate clearly to users what went wrong and suggest recovery actions when possible.

Example of problematic silent failure:
```tsx
{!!report && <TestCaseViewLoader report={report} tests={filteredTests.tests} />}
```

Better approach with explicit error handling:
```tsx
{!!report ? 
  <TestCaseViewLoader report={report} tests={filteredTests.tests} /> :
  <div className='error'>Report data could not be found</div>}
```

Even better with recovery guidance:
```tsx
{!!report ? 
  <TestCaseViewLoader report={report} tests={filteredTests.tests} /> :
  <div className='error'>
    Report data could not be found. Try refreshing the page or check your connection.
  </div>}
```

This principle ensures users understand when something has gone wrong rather than being left with confusing blank screens or unresponsive interfaces.

---

## prefer std::error_code parameters

<!-- source: hyprwm/Hyprland | topic: Error Handling | language: C++ | updated: 2025-04-17 -->

When using std::filesystem operations, prefer passing std::error_code parameters instead of relying on try-catch blocks for error handling. This approach provides better performance and more explicit error checking.

Most std::filesystem functions have overloads that accept an std::error_code reference parameter. Use these overloads and check the error code explicitly rather than catching exceptions.

Example:
```cpp
// Avoid try-catch approach
try {
    if (std::filesystem::exists(path) && std::filesystem::is_directory(path)) {
        // process directory
    }
} catch (...) {
    // handle error
}

// Prefer error_code approach
std::error_code ec1, ec2;
if (std::filesystem::exists(path, ec1) && !ec1 && 
    std::filesystem::is_directory(path, ec2) && !ec2) {
    // process directory
} else if (ec1 || ec2) {
    // handle specific errors
}
```

This pattern is especially important for operations like `std::filesystem::exists()`, `std::filesystem::is_directory()`, `std::filesystem::canonical()`, and directory iteration where exceptions can be thrown for various system-level issues. The error_code approach allows for more granular error handling and avoids the performance overhead of exception handling in expected error scenarios.

---

## validate external input safely

<!-- source: electron/electron | topic: Security | language: Other | updated: 2025-04-17 -->

Always validate and sanitize external input using established libraries rather than manual string manipulation or custom parsing. External input includes user data, environment variables, command line arguments, and data from untrusted sources. Manual construction of structured data (like JSON) with user input creates injection vulnerabilities.

Use proper validation libraries from //base or //v8 instead of manual string operations. For example, instead of manually constructing JSON:

```cpp
// UNSAFE - Manual JSON construction
std::wstringstream stm;
stm << L"[";
std::for_each(data, data + dataCount, [&](const auto& item) {
  stm << item << L",";  // No escaping, injection risk
});
stm << L"]";

// SAFE - Use proper JSON library
base::Value::List json_array;
for (const auto& item : data) {
  json_array.Append(base::Value(SanitizeInput(item)));
}
```

This principle applies to all external data sources: environment variables that could bypass security controls, user input in notifications, permission callbacks, and any data crossing trust boundaries. The goal is to prevent injection attacks and ensure data integrity through proper validation and sanitization.

---

## Consistent Identifier Naming

<!-- source: mermaid-js/mermaid | topic: Naming Conventions | language: Markdown | updated: 2025-04-17 -->

Use consistent, standards-aligned naming for identifiers, especially for user-facing text/URLs and registry keys.

- ID casing: Use `ID` (not `Id`) when it’s normal prose/descriptions; only use `Id` if an external API/storage contract explicitly requires it.
- URL/path naming: Use `kebab-case` for URL segments and related identifiers that mirror URLs.
- Registry keys: Use a stable `kebab-case` canonical key for shape/component registration; if you add an alias, make it explicit and short, and keep both entries consistent with docs/config.

Example (shape registry + ID prose):
```ts
// Canonical kebab-case registry key (and optional explicit alias)
const shapes = {
  'my-new-shape': myNewShape,
  'm-nsh': myNewShape,
};

// Documentation prose should use ID
// "ID of the edge" (unless an external API contract requires "Id")
```

---

## optimize workflow triggers

<!-- source: hyprwm/Hyprland | topic: CI/CD | language: Yaml | updated: 2025-04-17 -->

Design CI/CD workflows with intentional triggers and conditions to avoid unnecessary executions, rate limiting, and contextually inappropriate behavior. Use specific event triggers and conditional statements to ensure workflow steps run only when needed and appropriate.

Avoid overly broad automation like daily cron jobs that can cause rate limiting issues as your project scales. Instead, rely on event-driven triggers and manual execution when needed.

For steps that should only run in specific contexts, use conditional execution:

```yaml
- name: clang-format apply
  if: failure() && github.event_name == 'pull_request'
  run: ninja -C build clang-format

- name: Comment patch  
  if: failure() && github.event_name == 'pull_request'
  uses: mshick/add-pr-comment@v2
```

Consider separating workflows by purpose rather than adding complex conditions to a single workflow. This improves maintainability and reduces the risk of unintended executions.

---

## Define API boundaries

<!-- source: vercel/turborepo | topic: API | language: Other | updated: 2025-04-14 -->

Clearly specify what constitutes your public API contract to manage versioning expectations and documentation requirements. Distinguish between structured outputs intended for programmatic consumption versus human-readable outputs that may change without being considered breaking changes.

For CLI tools or libraries:
- Document which outputs follow semantic versioning guarantees
- Explicitly mark pre-stable APIs in documentation
- Be precise about response formats and headers in endpoint documentation

Example in package exports:
```json
{
  "exports": {
    // Public API with stability guarantees
    ".": "./src/public-api.ts",
    
    // Explicitly mark experimental features
    "./experimental": "./src/experimental-features.ts",
    
    // Internal APIs not covered by semver
    "./internal": null
  }
}
```

When documenting API endpoints, be specific about response headers and their purposes, such as `x-artifact-tag` for artifact download endpoints. For authentication endpoints, clearly document their scope and intended usage contexts.

---

## Follow support tiers

<!-- source: Homebrew/brew | topic: Configurations | language: Markdown | updated: 2025-04-12 -->

Configure your Homebrew installation according to the defined support tiers to ensure optimal functionality and support. For Tier 1 support (fully supported):

- Install in the default prefix (`/opt/homebrew` on Apple Silicon, `/usr/local` on Intel x86_64, `/home/linuxbrew/.linuxbrew` on Linux)
- Use officially supported Apple hardware (not Hackintosh or with OpenCore Legacy Patcher)
- Run on current macOS versions (latest and two previous versions) or supported Linux distributions
- Install on internal storage, not external drives
- Use the appropriate architecture for your platform

Non-standard configurations will receive reduced support (Tier 2 or 3) or may be entirely unsupported. When using shared dotfiles across platforms, use platform detection:

```sh
command -v brew || export PATH="/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:/usr/local/bin"
command -v brew && eval "$(brew shellenv)"
```

---

## API documentation clarity

<!-- source: prettier/prettier | topic: API | language: Markdown | updated: 2025-04-10 -->

Ensure API documentation provides clear, accurate, and comprehensive information for developers. This includes precise function signatures, detailed parameter descriptions, correct terminology, and helpful external references.

Key practices:
- Use accurate technical terminology (e.g., "file basename or extension" instead of vague descriptions)
- Include complete function signatures that reflect actual usage patterns
- Provide helpful context and examples for complex parameters
- Add links to relevant external documentation when referencing standard APIs
- Fix typos and grammatical errors that could confuse developers

Example of good API documentation:
```ts
// Clear function signature with proper typing
function parse(text: string, options?: ParserOptions): Promise<AST> | AST;

// Detailed parameter description with examples
// The `file` parameter could be a normal path or a url string like `file:///C:/test.txt`

// Helpful external reference
Strings provided to `plugins` are ultimately passed to [`import()` expression](https://nodejs.org/api/esm.html#import-expressions)
```

This approach helps developers understand exactly how to use APIs correctly and reduces confusion about parameter types, optional arguments, and expected behaviors.

---

## Respect language-specific conventions

<!-- source: zed-industries/zed | topic: Code Style | language: Toml | updated: 2025-04-08 -->

Always adhere to the established formatting and syntax conventions of each programming language while maintaining consistency across related language configurations. This includes:

1. Using the correct indentation style for each language (e.g., hard tabs for Go)
2. Applying similar configurations to related languages (e.g., if adding block comments to JavaScript, also add them to TypeScript)
3. Maintaining consistent organization within configuration files (e.g., keeping dependencies sorted alphabetically)

Example:
```toml
# For Go
tab_size = 4
hard_tabs = true

# For JavaScript and related languages
line_comments = ["// "]
block_comment = ["/*", "*/"]
```

Following language-specific conventions improves code readability, leverages standard tooling, and helps maintain consistency across the codebase, especially when working with multiple languages in the same project.

---

## optimize with bit manipulation

<!-- source: hyprwm/Hyprland | topic: Algorithms | language: Other | updated: 2025-04-07 -->

Use bit manipulation techniques to optimize memory usage and computational efficiency in data structures and enums. For flag enums, consistently use bit-shift notation `(1 << n)` to make bit positions explicit and enable efficient bitwise operations. For compact data representation, leverage bitfields within unions to pack multiple boolean flags into minimal memory space.

Example of bit-shift enum notation:
```cpp
enum eRectCorner {
    CORNER_NONE        = 0,
    CORNER_TOPLEFT     = 1 << 0,
    CORNER_TOPRIGHT    = 1 << 1,
    CORNER_BOTTOMRIGHT = 1 << 2,
    CORNER_BOTTOMLEFT  = 1 << 3
};
```

Example of bitfield optimization:
```cpp
union {
    uint16_t all = 0;
    struct {
        bool buffer : 1;
        bool damage : 1;
        bool scale : 1;
        // ... more flags
    };
};
```

This approach reduces memory footprint, enables efficient bitwise operations for flag combinations, and leverages compiler optimizations for bit manipulation algorithms.

---

## Nest related configuration options

<!-- source: helix-editor/helix | topic: Configurations | language: Markdown | updated: 2025-04-06 -->

Group related configuration options into nested TOML sections rather than using flat key-value pairs. This improves readability, maintainability, and makes relationships between settings more explicit.

Example:
Instead of:
```toml
word-completion = true
word-completion-trigger-length = 7
```

Use:
```toml
[word-completion]
enable = true
trigger-length = 7
```

This approach:
- Makes configuration hierarchies clear
- Groups related settings together
- Reduces naming conflicts and redundancy
- Improves configuration file organization
- Makes it easier to add related options in the future

When adding new configuration options, consider if they logically belong in an existing section or warrant creating a new nested section.

---

## Document build configuration changes

<!-- source: microsoft/playwright | topic: CI/CD | language: JavaScript | updated: 2025-04-03 -->

When modifying build tool configurations, especially during migrations, provide detailed technical justification for each change. Document why specific options, plugins, or flags are being added, removed, or modified with concrete reasoning.

This practice ensures build pipeline changes are transparent, maintainable, and can be properly reviewed. It prevents configuration drift and helps future developers understand the rationale behind build decisions.

Example of good documentation:
```javascript
// Remove babel plugins that are now redundant with esbuild:
// - "@babel/plugin-transform-logical-assignment-operators" - logical assignment 
//   has been natively supported since Node 15
// - "@babel/plugin-transform-nullish-coalescing-operator" - nullish coalescing 
//   has been natively supported since Node 14  
// - "@babel/plugin-transform-modules-commonjs" - handled by --format=cjs flag
args: [
  'esbuild',
  '--format=cjs',
  '--platform=node'
]
```

Always explain the technical basis for configuration decisions, reference version support when relevant, and note when options become obsolete due to dependency changes.

---

## disallow unsafe schemes

<!-- source: likec4/likec4 | topic: Security | language: TypeScript | updated: 2025-04-03 -->

Treat resource URIs and external references as untrusted input: normalize and validate schemes, and reject anything not on an explicit allowlist. Motivation: schemes such as file: (and other unsafe schemes like javascript: or data: when used for resources) can expose local files or enable injection attacks, and are commonly blocked by browsers — so they must not be implicitly trusted.

How to apply:
- Normalize inputs (trim, toLowerCase) before checking.
- Use an allowlist of safe schemes your app requires (e.g., https:, http:) and optionally permit safe relative paths. Reject all others by default.
- For user-provided paths that must reference internal assets, use server-side resolution/whitelisting rather than accepting raw URIs.

Example (pattern adapted from code under review):
// before: filtered out many schemes, but allowed file: was removed
filter(isString)
  .filter(s => {
    const v = s.trim().toLowerCase();
    // allow only http(s) or relative paths starting without a scheme
    return isTruthy(v) && (
      v.startsWith('http:') || v.startsWith('https:') || v.startsWith('.') || v.startsWith('/')
    );
  });

Notes and extensions:
- Consider also rejecting or special-casing other risky schemes (javascript:, data:) depending on context.
- Prefer server-side enforcement for sensitive resources and log/reject invalid attempts.
- Document allowed schemes for each API or component so callers know what is permitted.

---

## Minimize unnecessary operations

<!-- source: Homebrew/brew | topic: Performance Optimization | language: Ruby | updated: 2025-04-02 -->

Optimize performance by eliminating redundant operations and arranging code to avoid unnecessary computations, especially in frequently executed paths. Follow these principles:

1. **Move invariant operations outside of loops** - When an operation's result doesn't change between iterations, perform it only once:

```ruby
# Instead of this:
primary_container.dependencies.each do |dep|
  Homebrew::Install.perform_preinstall_checks_once
  # other operations...
end

# Do this:
Homebrew::Install.perform_preinstall_checks_once
primary_container.dependencies.each do |dep|
  # other operations...
end
```

2. **Read and process files once** - Cache file contents rather than repeatedly reading the same file:

```ruby
# Instead of repeatedly reading files in a loop:
formulae_and_casks_to_check.each do |formula_or_cask|
  autobump_file = formula_or_cask.tap.path/".github/autobump.txt"
  next false unless File.exist?(autobump_file)
  if File.read(autobump_file).include?(formula_or_cask.name)
    # ...
  end
end

# Read files once and cache the results:
autobump_files = {}
formulae_and_casks_to_check.each do |formula_or_cask|
  tap = formula_or_cask.tap
  next if tap.nil?

  autobump_files[tap] ||= begin
    autobump_path = tap.path/".github/autobump.txt"
    autobump_path.exist? ? File.read(autobump_path).lines.map(&:strip) : []
  end
  # Use cached content
end
```

3. **Cache expensive function results** - For slow operations, calculate once and reuse:

```ruby
# Cache expensive operation results
deploy_new_x86_64_runner = @all_supported || deploy_new_x86_64_runner?
```

4. **Order conditional checks efficiently** - Check simple, fast conditions before expensive operations:

```ruby
Formula.all.any? do |formula|
  # First check the simple condition
  next false if formula.class.pour_bottle_only_if != :clt_installed
  
  # Only then perform expensive dependency analysis
  non_test_dependencies = Dependency.expand(formula, cache_key: "determine-test-runners") do |_, dependency|
    Dependency.prune if dependency.test?
  end
  # ...
end
```

5. **Combine multiple iterations** - When performing multiple operations on the same collection, try to handle everything in a single pass rather than iterating multiple times.

These optimizations are particularly important in performance-critical paths that execute frequently or process large amounts of data.

---

## Validate performance impact first

<!-- source: vercel/turborepo | topic: Performance Optimization | language: Rust | updated: 2025-03-31 -->

Always validate performance changes through profiling or benchmarking before implementation, and favor memory-efficient patterns when making optimizations. Key practices:

1. Profile before/after significant changes:
```rust
// Before changing buffer sizes, validate impact:
const SCROLLBACK_LEN: usize = 1024;
// Profile current performance
// Test new value
const SCROLLBACK_LEN: usize = 2048;
// Validate no significant regression
```

2. Use memory-efficient patterns:
- Prefer `&str` over `&String` to avoid double indirection
- Initialize collections with capacity when size is known:
  ```rust
  let mut map = HashMap::with_capacity(items.len());
  ```
- Return iterators instead of collecting vectors when possible:
  ```rust
  // Instead of
  pub fn get_items(&self) -> Vec<String> {
      self.items.iter().map(|i| i.to_string()).collect()
  }
  // Prefer
  pub fn get_items(&self) -> impl Iterator<Item = &str> + '_ {
      self.items.iter().map(|i| i.as_str())
  }
  ```

3. Document performance-critical decisions with benchmarks or profiling results to justify changes.

---

## Secure authentication state files

<!-- source: microsoft/playwright | topic: Security | language: Markdown | updated: 2025-03-31 -->

Authentication state files (such as browser session files, cookies, or tokens) contain sensitive credentials that can lead to full account takeover if exposed. These files must never be committed to version control systems as they could be used to impersonate users or test accounts.

**Prevention strategies:**
1. **Use .gitignore**: Add authentication directories to your `.gitignore` file and store files in dedicated directories like `playwright/.auth/`
2. **External storage**: Store sensitive files outside the project directory using temporary directories

**Example implementation:**
```javascript
// Option 1: Secure directory with .gitignore
{
  name: 'firefox',
  use: {
    storageState: 'playwright/.auth/user.json', // Add playwright/.auth to .gitignore
  },
}

// Option 2: Temporary directory (safer)
{
  name: 'firefox', 
  use: {
    storageState: `${mkdirtemp()}/playwright/.auth/user.json`,
  },
}
```

Always verify that authentication state files are properly excluded from version control and build artifacts to prevent credential exposure.

---

## Environment variable management

<!-- source: vitejs/vite | topic: Configurations | language: Markdown | updated: 2025-03-28 -->

When working with environment variables in Vite applications, be explicit about variable loading behavior and precedence. Environment variables from `.env` files are always loaded regardless of mode, with mode-specific files (`.env.[mode]`) taking precedence over generic ones.

For type safety, use the TypeScript declaration merging pattern to strongly type your environment variables:

```typescript
/// <reference types="vite/client" />

// By adding this interface, you can make the type of ImportMetaEnv strict
// to disallow unknown keys.
interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  // more env variables...
}
```

When loading environment variables in config files, be explicit about which prefixes to include:

```javascript
import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  // Set the third parameter to 'APP_' to load envs with the `APP_` prefix.
  // If necessary, you can set the optional third parameter to '' to load all env regardless of the `VITE_` prefix.
  const env = loadEnv(mode, process.cwd(), 'APP_')

  return {
    // use env variables in config
    define: {
      'process.env.APP_ENV': JSON.stringify(env.APP_ENV)
    }
  }
})
```

To disable environment variable loading altogether, set `envDir: false` in your Vite config.

---

## consistent algorithm interfaces

<!-- source: neovim/neovim | topic: Algorithms | language: Txt | updated: 2025-03-28 -->

When designing interfaces for filtering, traversal, or search algorithms, research existing codebase patterns to maintain consistency in terminology and boolean logic. Before introducing new parameter names like "skip", "filter", "match", or "predicate", analyze which terms are already established in similar contexts.

Ensure clear documentation of predicate behavior, explicitly stating the expected return values and their effects:

```lua
-- Good: Clear documentation with explicit boolean logic
• {filter}? (`fun(dir: string): boolean`) Predicate that
  decides if a directory is traversed. Return true to traverse
  a directory, or false to skip.

-- Avoid: Ambiguous or inconsistent terminology
• {skip}? (`fun(dir: string): boolean`) Do not traverse
```

This consistency reduces cognitive load for developers and prevents confusion about whether predicates use positive logic (return true to include) or negative logic (return true to exclude). Research shows that "match" and "filter" are the most common patterns in established codebases, making them safer choices for new algorithm interfaces.

---

## avoid hardcoded configuration values

<!-- source: helix-editor/helix | topic: Configurations | language: Rust | updated: 2025-03-27 -->

Avoid hardcoding configuration values that affect user experience or behavior. Instead, make these values configurable with sensible defaults. This is especially important for timing values, thresholds, and user-facing constants that different users may want to customize.

Examples of values that should be configurable rather than hardcoded:
- Completion trigger thresholds: `const MIN_WORD_LEN: usize = 7;` should be configurable for users who want completion for shorter words like "because"
- Timing values: `const DEBOUNCE: Duration = Duration::from_secs(1);` should be configurable as users may prefer faster response times like 20ms
- Default tokens: `let token = token.unwrap_or("//");` should use a configurable default comment token rather than hardcoding "//"
- Timeout values: hardcoded timeouts like 30ms should be configurable for testing and different user preferences

When making values configurable:
```rust
// Instead of:
const MIN_WORD_LEN: usize = 7;

// Do:
pub struct CompletionConfig {
    pub min_word_length: usize,
}

impl Default for CompletionConfig {
    fn default() -> Self {
        Self {
            min_word_length: 7, // Reasonable default, but configurable
        }
    }
}
```

This approach improves user experience by allowing customization while maintaining reasonable defaults for users who don't need to change the settings.

---

## Use semantically clear names

<!-- source: microsoft/playwright | topic: Naming Conventions | language: TSX | updated: 2025-03-27 -->

Names should clearly communicate their actual purpose and be consistent across similar contexts. Avoid names that mislead about functionality or create confusion about the component's role.

When naming components, props, or UI elements, ensure the name accurately reflects what the code does rather than what it might do. For example, if a component handles a single checkbox, don't name it in a way that suggests it handles multiple checkboxes.

Maintain consistency in naming patterns, especially for UI elements. If you show additional text in one context, apply the same pattern consistently rather than making it conditional.

Example of unclear naming:
```tsx
// Misleading - suggests multiple checkboxes but handles one
export const CheckBox: React.FunctionComponent<{
    checkBoxSettings: Check<boolean>[];
}>

// Conditional labeling creates inconsistency  
{isFailed && <span>View Trace</span>}
```

Example of clear naming:
```tsx
// Clear - accurately reflects single checkbox functionality
export const CheckBox: React.FunctionComponent<{
    settings: Check<boolean>;
}>

// Consistent and semantically meaningful
<span>View Failing Trace</span>
```

The goal is to make code self-documenting through meaningful names that eliminate ambiguity about purpose and maintain consistent patterns.

---

## In-tree build configurations

<!-- source: ghostty-org/ghostty | topic: CI/CD | language: Yaml | updated: 2025-03-26 -->

Keep all build configuration files (Snapcraft, Flatpak manifests, etc.) in the repository alongside your code to ensure they are tested, versioned, and maintained together with the application. This approach facilitates CI testing, allows for regression detection, and ensures consistency across distribution methods.

Include multiple build variants when appropriate (e.g., release vs. development builds):

```yaml
# Example Flatpak manifest with development variant
app-id: com.example.app
runtime: org.gnome.Platform
# ... common configuration ...

# Production build
modules:
  - name: app
    buildsystem: simple
    build-commands:
      - zig build -Doptimize=ReleaseFast

# With corresponding development variant
# com.example.app.Devel.yml
app-id: com.example.app.Devel
runtime: org.gnome.Platform
# ... common configuration ...
modules:
  - name: app
    buildsystem: simple
    build-commands:
      - zig build -Doptimize=Debug
```

Configure your CI workflows to verify all distribution methods on appropriate triggers (e.g., only run on relevant branches) and optimize test matrices by eliminating redundant tests that wouldn't provide additional signal. This ensures reliable builds across all supported platforms while keeping CI/CD pipelines efficient.

---

## Document configuration constraints clearly

<!-- source: zed-industries/zed | topic: Configurations | language: Markdown | updated: 2025-03-24 -->

When defining configuration options, always clearly document parameter constraints, valid ranges, and behaviors. For numeric values, explicitly state acceptable ranges and how out-of-range values are handled. Configuration options should have appropriate granularity - avoid simple booleans when more nuanced control is beneficial.

For example, instead of:
```json
{
  "diagnostics": {
    "include_warnings": true
  }
}
```

Consider more granular control:
```json
{
  "diagnostics": {
    "minimum_level": "warning",  // Options: "error", "warning", "info", "hint"
    "inline": {
      "enabled": true
    }
  }
}
```

Group related settings logically, provide sensible defaults, and ensure configuration structure reflects the natural workflow (prerequisites before implementation details). This makes configurations more intuitive, flexible, and less prone to user error.

---

## Handle configuration value changes

<!-- source: microsoft/vscode | topic: Configurations | language: TypeScript | updated: 2025-03-24 -->

Configuration values should be properly initialized and stay updated throughout their lifecycle. Follow these guidelines:

1. Initialize configuration values immediately upon service creation, not just in change handlers:
```ts
class ConfigurationAwareService {
  private _configValue: number;
  
  constructor(@IConfigurationService configService: IConfigurationService) {
    // Initialize immediately
    this._configValue = configService.getValue('myConfig');
    
    // Listen for changes
    this._register(configService.onDidChangeConfiguration(e => {
      if (e.affectsConfiguration('myConfig')) {
        this._configValue = configService.getValue('myConfig');
      }
    }));
  }
}
```

2. For frequently accessed configurations, cache the value and update via change events rather than querying on each use:
```ts
// AVOID: Querying on each use
getConfig() {
  return this.configService.getValue('myConfig');
}

// BETTER: Cache and update on changes
private _cachedConfig = this.configService.getValue('myConfig');
getConfig() {
  return this._cachedConfig;
}
```

3. When handling configuration changes, use `affectsConfiguration()` to efficiently check if your configuration was modified before updating cached values.

4. For services that depend on initial configuration state, ensure values are available before service initialization or handle the undefined case appropriately.

---

## API documentation accuracy

<!-- source: helix-editor/helix | topic: API | language: Markdown | updated: 2025-03-24 -->

Ensure API documentation accurately describes actual behavior and avoids subjective commentary that may become outdated. Documentation should clearly explain how features interact, what the expected behavior is, and avoid qualitative assessments about performance or quality that can change over time.

When documenting APIs or software integrations, focus on factual descriptions of functionality rather than opinions about how well something works. For example, instead of saying "Seems to work less well than Dance" in a comparison table, simply list the available options without subjective commentary.

Additionally, when API behavior might be misunderstood, provide clear explanations. For instance, if documentation suggests "only one language server can be used for each feature" but the actual behavior allows multiple servers for some features like diagnostics, clarify this discrepancy with additional documentation.

Example of good practice:
```toml
# Clear, factual description
[language-server.efm-lsp-prettier]
command = "efm-langserver"
# Explains actual behavior without opinion
config = { documentFormatting = true }
```

This approach keeps documentation maintainable, prevents user confusion, and ensures that API behavior is accurately represented to developers.

---

## Standardize API integration patterns

<!-- source: Homebrew/brew | topic: API | language: Ruby | updated: 2025-03-21 -->

Establish consistent patterns for API integrations by following these guidelines:

1. Document API endpoint usage specifically:
- Clearly specify which components use each endpoint
- Include expected request/response formats
- Document any authentication requirements

2. Standardize request handling:
```ruby
# Good - Clear request configuration
def api_request(url_options)
  type = if (data = url_options[:data].presence)
    :data
  elsif (data = url_options[:json].presence)
    :json
  end
  
  case data
  when Hash
    if type == :json
      ["--#{type}", JSON.generate(data)]
    else
      ["--#{type}", URI.encode_www_form(data)]
    end
  end
end
```

3. Handle API response evolution:
- Document field deprecations clearly
- Consider backwards compatibility needs
- Provide migration paths for breaking changes

4. Implement consistent error handling:
- Handle API-specific errors explicitly
- Provide meaningful error messages
- Include fallback behaviors where appropriate

This standardization ensures maintainable and reliable API integrations while promoting clear documentation and consistent implementation patterns across the codebase.

---

## Separate configuration responsibilities

<!-- source: vitejs/vite | topic: Configurations | language: Other | updated: 2025-03-21 -->

Design configuration files with clear separation of responsibilities and maintain flexibility for future changes. Avoid unnecessarily bundling configurations together when they serve different purposes, as this can create tight coupling and make future transitions difficult.

For tool-specific configurations (like babel, webpack, etc.), keep them in their dedicated files rather than abstracting them in framework plugins. This allows users to:
1. Have full visibility into their build pipeline
2. Customize configurations as needed
3. Swap underlying tools without major refactoring

When creating configuration patterns (like in renovate.json5, .gitignore, etc.), be as specific as possible when targeting special cases:

```json
// Instead of broad patterns like this:
{
  "fileMatch": ["\\.[mc]?[tj]sx?$"]
}

// Use specific targeting when appropriate:
{
  "fileMatch": ["packages\/create-vite\/src\/index\\.ts$"]
}
```

This approach reduces the risk of unintended matches and makes configurations more maintainable and transparent.

---

## omit redundant configuration

<!-- source: helix-editor/helix | topic: Configurations | language: Toml | updated: 2025-03-19 -->

Remove configuration keys that explicitly set values identical to their defaults. This reduces visual clutter, minimizes maintenance overhead, and prevents confusion about which settings are intentionally customized versus accidentally duplicated.

When reviewing configuration files, identify and remove keys that match default behavior. For example:

```toml
# Before - unnecessary explicit defaults
[[language]]
name = "werk"
scope = "source.werk"
file-types = [ "werk", { glob = "Werkfile" } ]
roots = []  # Remove: [] is the default
language-id = "werk"  # Remove: matches name by default

# After - clean configuration
[[language]]
name = "werk"
scope = "source.werk"
file-types = [ "werk", { glob = "Werkfile" } ]
```

This practice helps distinguish between intentional configuration choices and default values, making the actual customizations more apparent to future maintainers.

---

## Secure workflow permissions

<!-- source: vitejs/vite | topic: CI/CD | language: Yaml | updated: 2025-03-18 -->

Define explicit and minimal permissions in GitHub Actions workflows to ensure proper operation while maintaining security. Workflows should only have permissions necessary for their intended tasks, and permission checks should occur early in the workflow to prevent unnecessary actions.

For workflows that modify resources:
- Add specific permission scopes (e.g., `issues: write` for workflows that close issues)
- Use empty `permissions: {}` as a default and add only what's needed
- Place permission validation at the top of workflows to fail fast

Example:
```yaml
name: Issue Management Workflow

# Start with empty permissions
permissions: {}

jobs:
  manage-issues:
    runs-on: ubuntu-latest
    # Add only required permissions
    permissions:
      issues: write
    
    steps:
      # Check user permissions first before proceeding
      - name: Check User Permissions
        uses: actions/github-script@v7
        with:
          script: |
            // Verify user has appropriate permissions
            if (!context.payload.sender.permissions.write) {
              core.setFailed('User does not have write permissions')
              return
            }
            
      # Remaining steps only execute if permissions check passes
      - name: Close stale issues
        # ...
```

This approach minimizes security risks, prevents workflow failures due to permission issues, and follows the principle of least privilege.

---

## Background process blocking operations

<!-- source: zed-industries/zed | topic: Concurrency | language: Rust | updated: 2025-03-17 -->

Always move potentially blocking operations to background threads to maintain UI responsiveness. Use appropriate spawning mechanisms based on the operation type:

1. For CPU-intensive work or file operations:
```rust
// Don't do this - blocks main thread
let result = heavy_computation();

// Do this instead
cx.background_spawn(async move {
    let result = heavy_computation();
    // Update state after computation
}).await;
```

2. For state updates after background work:
```rust
// Accumulate new state first
let new_state = cx.background_spawn(async move {
    let mut new_data = Vec::new();
    // ... heavy computation ...
    new_data
}).await;

// Then update actual state once
self.state = new_state;
```

Key principles:
- Use cx.background_spawn() for CPU-intensive operations
- Keep main thread operations light and UI-focused
- Accumulate state changes in background before applying
- Consider using rate limits for multiple concurrent operations

This pattern is essential for maintaining application responsiveness and preventing UI freezes.

---

## Document protocol configurations clearly

<!-- source: vitejs/vite | topic: Networking | language: Markdown | updated: 2025-03-17 -->

When documenting network protocol configurations (TLS, HTTP/2, CORS), provide specific details about required options, default values, and explicit behavior. Avoid ambiguous terminology like "sufficient values" and instead specify exactly what options are needed and how different settings interact.

For example, instead of writing:
```md
Enable TLS + HTTP/2. Note this downgrades to TLS only when the `server.proxy` option is also used.

The value is an options object passed to `https.createServer()`.
```

Prefer more explicit documentation with required parameters:
```md
Enable TLS + HTTP/2. The value is an [options object](https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener) passed to `https.createServer()`.

Required options include `key`/`cert` or `pfx` for server identity. Using `server.proxy` will disable HTTP/2 while maintaining TLS support.
```

For default configuration values, include the actual implementation details as seen in the CORS example, which clearly specifies the regex pattern for allowed origins. This precision prevents confusion, reduces follow-up questions, and ensures developers can implement network features correctly and securely.

---

## Follow established conventions

<!-- source: helix-editor/helix | topic: Code Style | language: Toml | updated: 2025-03-12 -->

Configuration settings should align with official language documentation and established community standards rather than arbitrary personal preferences. This applies to indentation styles, formatter configurations, and syntax requirements.

For language-specific settings, consult official documentation:
- Use 2 spaces for Typst indentation as specified in official docs, not 4
- Follow PEP 8 for Python when setting required indentation
- Only enable auto-format when it's standard practice for the language

For tool configurations, ensure commands and arguments are syntactically correct:
```toml
# Correct formatter configurations
formatter = { command = "prettier", args = ["--parser", "typescript"] }
formatter = { command = "biome", args = ["format", "--stdin-file-path=a.js"] }
formatter = { command = "deno", args = ["fmt", "--ext", "js"] }

# Use full 6-character hex codes, not 3-character shortcuts
"ui.background" = { bg = "#262335" }  # not "#263"
```

This ensures consistency with ecosystem expectations and prevents configuration errors that could break functionality.

---

## Centralize configuration values

<!-- source: ghostty-org/ghostty | topic: Configurations | language: Yaml | updated: 2025-03-12 -->

{% raw %}
Hardcoded configuration values scattered throughout codebases create maintenance burdens and increase the risk of inconsistency. Define configuration values (like versions, paths, and feature flags) in a single location and reference them elsewhere.

For build systems and CI workflows:
- Extract repeated values like dependency versions into variables at the top level
- Use environment variables or central config files rather than duplicating values
- Document the purpose and constraints of configuration variables

Example:
```yaml
# GOOD: Define version at the top level
env:
  ZIG_VERSION: "0.13.0"

jobs:
  build:
    steps:
      - name: Setup Zig
        uses: goto-bus-stop/setup-zig@v2
        with:
          version: ${{ env.ZIG_VERSION }}
          
  test:
    steps:
      - name: Build with Zig
        run: zig-${ZIG_VERSION} build test
```

This approach makes version updates simpler, reduces errors from inconsistent values, and makes configuration more maintainable. For complex configurations, consider creating a dedicated configuration module that can be imported by other components of the system.
{% endraw %}

---

## Generate dynamic configurations

<!-- source: ghostty-org/ghostty | topic: Configurations | language: Xml | updated: 2025-03-12 -->

Always generate configuration files programmatically when they contain dynamic content that changes frequently or needs to stay in sync with the application (like version numbers, release dates, or build timestamps). Manual maintenance of such files is tedious, error-prone, and creates maintenance overhead.

For example, instead of manually updating version information in XML metadata files:

```xml
<!-- Avoid manual updates like this -->
<releases>
  <release version="1.0.1" date="2024-12-31">
    <url type="details">https://ghostty.org/docs/install/release-notes/1-0-1</url>
  </release>
</releases>
```

Generate these files during the build process:

```bash
# Generate at build time to ensure consistency with application version
generate_appdata_xml --version="$APP_VERSION" --build-date="$(date +%Y-%m-%d)" --release-notes-url="https://ghostty.org/docs/install/release-notes/$APP_VERSION"
```

This approach ensures configuration files stay synchronized with the application state and eliminates manual update errors.

---

## Pin configuration versions

<!-- source: python-poetry/poetry | topic: Configurations | language: Dockerfile | updated: 2025-03-10 -->

Always pin specific versions for base images, dependencies, and environment configurations to ensure reproducible builds and prevent unexpected failures from upstream changes.

When configuring Docker images, development containers, or dependency management tools, specify exact versions rather than using generic tags like "latest" or broad version ranges. This prevents builds from breaking when upstream maintainers release new versions or change default behaviors.

Example from Docker configurations:
```dockerfile
# Instead of generic versions
FROM python:3

# Use pinned versions
FROM python:3.11-slim-bookworm

# Pin dependency versions
ARG POETRY_VERSION=1.8
RUN pip install "poetry==${POETRY_VERSION}"
```

This practice is especially critical for:
- Base Docker images (pin both Python version and OS distribution)
- Package manager versions (Poetry, pip, etc.)
- Development container images
- CI/CD environments

The small overhead of occasionally updating pinned versions is far outweighed by the stability and predictability gained, particularly when upstream changes can introduce security vulnerabilities or breaking changes that affect your build process.

---

## Document configs comprehensively

<!-- source: ghostty-org/ghostty | topic: Configurations | language: Other | updated: 2025-03-08 -->

Configuration options must be documented comprehensively with:

1. Clear, descriptive name using appropriate platform prefixes (e.g., 'gtk-' for GTK-specific options)
2. Detailed explanation of the option's purpose and effect
3. Default value and valid value ranges
4. Version compatibility information if relevant
5. Example usage and specific use cases when the option might be needed

Example of well-documented config:

```zig
/// Controls whether to disable GDK color management in GTK applications.
///
/// By default this is set to `false`, meaning color management is enabled.
/// You may want to enable this setting (set to `true`) if you experience:
/// - Incorrect or washed out colors in your terminal
/// - Color inconsistencies between GTK applications
/// - Performance issues related to color management
///
/// This is a workaround for known issues with GTK's color management implementation,
/// particularly affecting applications running under Wayland.
/// Fixed in GTK 4.15.6.
@"gtk-gdk-disable-color-mgmt": bool = false,
```

Poor documentation can lead to user confusion, support issues, and inconsistent usage. Clear documentation helps users understand when and how to use configuration options effectively.

---

## Simplify complex code blocks

<!-- source: Homebrew/brew | topic: Code Style | language: Ruby | updated: 2025-03-06 -->

Break down complex code blocks and expressions into simpler, more readable components. Complex boolean logic, nested conditions, and multi-operation lines should be refactored for clarity.

Key practices:
1. Split complex boolean expressions into named variables or helper methods
2. Break long one-liners into multiple lines
3. Prefer positive conditions over negative ones
4. Use early returns to reduce nesting

Example - Before:
```ruby
return unless artifacts.reject do |k|
  k.is_a?(::Cask::Artifact::Font)
end.empty?
```

After:
```ruby
return if artifacts.all?(::Cask::Artifact::Font)
```

Or when dealing with complex conditions:

Before:
```ruby
print_stderr = !(verbose && show_info).nil?
```

After:
```ruby
print_stderr = if verbose && show_info
  true
else
  false
end
```

This approach makes code easier to read, understand, and maintain while reducing the cognitive load on reviewers and future maintainers.

---

## Vue component import handling

<!-- source: vitejs/vite | topic: Vue | language: TypeScript | updated: 2025-03-06 -->

When working with Vue single-file components, pay special attention to how imports are processed, particularly with query parameters. URL handling can significantly impact module resolution and hot module replacement (HMR).

Ensure proper handling of URLs with query parameters when importing Vue components to prevent duplicate entries in the module graph. For example, when a `.html?vue` file has additional query parameters like `&lang.js`, injecting further parameters (like `?import`) can cause issues.

```js
// Potentially problematic:
import Component from './Component.vue?custom=param&lang.js'

// Consider how query parameters are processed in your build tooling
// Be careful when manually adding parameters to imports
```

Also note that HMR behavior differs between file update, create, and delete operations. Custom HMR plugins only run on 'update' events by default, not on 'create' or 'delete'. When developing components that rely on HMR, test all file operations to ensure proper reactivity during development.

---

## Hybrid monorepo testing

<!-- source: vercel/turborepo | topic: Testing | language: Other | updated: 2025-03-05 -->

When working with tests in a monorepo, implement a hybrid testing approach that balances local development experience with CI performance. Set up local Vitest configurations in each package while also configuring a root workspace for unified testing. This preserves Turborepo's caching benefits in CI while providing a better developer experience.

Always explicitly specify coverage outputs in your Turborepo configuration:

```json
{
  "tasks": {
    "test": {
      "dependsOn": ["^test", "@repo/vitest-config#build"],
      "outputs": ["coverage/**"]  // Explicitly define coverage output paths
    },
    "merge-json-reports": {
      "inputs": ["coverage/raw/**"],
      "outputs": ["coverage/merged/**"]
    },
    "report": {
      "dependsOn": ["merge-json-reports"],
      "inputs": ["coverage/merge"],
      "outputs": ["coverage/report/**"]
    }
  }
}
```

This approach enables you to efficiently run tests locally during development while maintaining proper caching for CI environments and generating comprehensive coverage reports that can be merged across packages.

---

## Minimize memory allocations

<!-- source: vitejs/vite | topic: Performance Optimization | language: TypeScript | updated: 2025-03-04 -->

Choose methods and patterns that reduce unnecessary memory allocations and object creation to improve performance. When working with buffers, prefer direct methods like `Buffer.byteLength()` over approaches that create intermediate objects:

```javascript
// Less efficient - creates an unnecessary buffer object in memory
const size = Buffer.from(chunk.code).length;

// More efficient - calculates the byte length directly
const size = Buffer.byteLength(chunk.code);
```

When handling object operations, avoid deep cloning when only specific properties are needed. Use targeted cloning strategies based on the actual requirements:

```javascript
// Less efficient - may clone objects unnecessarily
function deepClone<T>(value: T): T {
  if (Array.isArray(value)) {
    return value.map((v) => deepClone(v)) as T;
  }
  if (isObject(value)) {
    const cloned: Record<string, any> = {};
    for (const key in value) {
      cloned[key] = deepClone(value[key]);
    }
    return cloned as T;
  }
  // Only use structuredClone for complex types that need it
  if (value instanceof RegExp) {
    return structuredClone(value);
  }
  return value as T;
}
```

Be mindful of expensive operations like `structuredClone()` which can significantly impact performance on basic primitives. Consider using specialized handling for different data types to optimize memory usage and processing time.

---

## Keep build tooling updated

<!-- source: vercel/turborepo | topic: CI/CD | language: Json | updated: 2025-03-03 -->

Maintain up-to-date build and CI/CD tooling to leverage the latest features, performance improvements, and security patches. Regularly check for updates to build orchestration tools like Turborepo and use provided codemods for seamless upgrades. When configuring build pipelines, optimize task dependencies by using topological approaches (like Turborepo's `topo` mode) to enable more efficient parallel execution. Additionally, when adding new scripts to your workflow, ensure proper execution order by establishing clear dependencies between build steps.

Example:
```json
{
  "name": "project",
  "devDependencies": {
    "turbo": "^2.0.0"  // Using latest major version
  },
  "scripts": {
    "upgrade-turbo": "npx @turbo/codemod upgrade",
    "build": "turbo run build",
    "preview-storybook": "turbo run build preview-storybook" // Ensuring build runs first
  },
  "turbo": {
    "pipeline": {
      "test": {
        "dependsOn": ["^test"],
        "dependencyMode": "topo" // Only block on actual dependencies
      }
    }
  }
}
```

---

## Semantics-Preserving Formatting

<!-- source: mermaid-js/mermaid | topic: Code Style | language: Html | updated: 2025-03-03 -->

Code-style changes (formatting, spacing, selector tweaks, spell/lint adjustments) must not alter semantics or intended content.

- CSS: scope styling to the minimal element needed (avoid global or overly broad selectors). Prefer targeted selectors like:
  ```css
  div.mermaid svg:first-of-type {
    border: 2px solid darkred;
  }
  ```
- Strings/markup: preserve exact characters across line breaks and escaping. If a split token is intentional (e.g., for XSS test payload construction), don’t “join”/reformat it in a way that changes the resulting string.
- Tooling noise: if spellcheck/lint flags intentionally split/obfuscated content, suppress it explicitly (e.g., via a dedicated `codespell-ignore` pragma) rather than changing the underlying payload.

This prevents unintended styling regressions and avoids subtle bugs from formatting-induced content changes.

---

## Standardize build configuration patterns

<!-- source: helix-editor/helix | topic: Configurations | language: Other | updated: 2025-02-27 -->

Explicitly define and standardize build configuration patterns across the project to ensure consistent behavior and optimal performance. Use explicit build type declarations and separate configurations for development and release builds.

Key points:
1. Use explicit build type declarations (e.g., 'release' vs 'debug')
2. Separate development and production configurations
3. Consider performance implications of build options

Example:
```nix
# Good: Explicit build configuration
packages = eachSystem (system: {
  default = pkgs.callPackage mkHelix {
    cargoBuildType = "release";  # Explicit build type
    rustPlatform = stableToolchain;  # Production toolchain
  };
  
  # Debug build with development toolchain
  debug = pkgs.callPackage mkHelix {
    cargoBuildType = "debug";
    rustPlatform = devToolchain;
  };
});

# Avoid: Implicit or mixed configurations
packages = eachSystem (system: {
  default = pkgs.callPackage mkHelix {};  # Implicit build type
});
```

This pattern ensures clear separation between development and production builds, makes configuration intentions explicit, and helps prevent unintended performance impacts from build options.

---

## Use workspace dependencies consistently

<!-- source: vercel/turborepo | topic: Configurations | language: Toml | updated: 2025-02-27 -->

Always use workspace-level dependency declarations (`workspace = true`) rather than specifying exact versions in individual crates. This ensures consistency across your project, simplifies maintenance, and reduces the risk of version conflicts.

When adding or updating dependencies:
1. Check if the dependency already exists at the workspace level
2. Use the workspace reference syntax when possible
3. If you need to modify features or settings, maintain the workspace reference

Example:
```diff
- git2 = { version = "0.19.0", default-features = false }
+ git2 = { workspace = true, default-features = false }
```

or

```diff
- futures = "0.3.30"
+ futures = { workspace = true }
```

This practice centralizes dependency management at the workspace level, making updates and security patches easier to apply consistently across all crates.

---

## Deterministic Testing Practices

<!-- source: mermaid-js/mermaid | topic: Testing | language: JavaScript | updated: 2025-02-26 -->

Integration/e2e tests should be deterministic and directly tied to specified behavior.

Apply these rules:
1) Avoid time-based waits. Wait for an observable condition (DOM element present, network idle, event emitted, SVG rendered) instead of `cy.wait(500)`.
2) Make syntax/format expectations strict. When behavior depends on parsing (e.g., `dateRange`), define the accepted format precisely and test the exact edge cases (whitespace/colon/spacing variants, valid date-only/time-only/date+time cases).
3) Eliminate flakiness from external assets. For font/icon rendering, use a stable local asset source and/or wait for fonts to finish loading before rendering/asserting.
4) Keep snapshot identifiers stable. If your visual tests compare images, avoid changing snapshot keys/titles; add tests within existing `describe` blocks to prevent snapshot mismatch.

Example (replace time-based waits):
```js
// Bad (flaky)
cy.wait(500);

// Prefer (event/condition-based)
cy.get('svg', { timeout: 10_000 }).should('exist');
// or: wait for a specific rendered marker / data attribute
// cy.get('[data-testid="render-complete"]', { timeout: 10_000 }).should('be.visible');
```

Example (strict format tests for parsing):
```js
const ok = 'dateRange : 13:00, 14:00';
const bad1 = 'dateRange: 13:00, 14:00';
const bad2 = 'dateRange 13:00, 14:00';

expect(parserFnConstructor(`gantt\n${ok}`)).not.toThrow();
expect(parserFnConstructor(`gantt\n${bad1}`)).toThrow();
expect(parserFnConstructor(`gantt\n${bad2}`)).toThrow();
```

---

## consistent naming conventions

<!-- source: helix-editor/helix | topic: Naming Conventions | language: Toml | updated: 2025-02-26 -->

Maintain consistent naming patterns throughout your codebase, following established conventions and ensuring uniformity within the same context. This includes using correct syntax for configuration values, matching case conventions for related identifiers, organizing entries systematically (like alphabetically), and choosing descriptive names that clearly indicate purpose.

Examples of good practices:
- Use `underlined` instead of `underline` in modifier arrays to match the established API
- Match case conventions: use `selectionfg` consistently instead of mixing `selectionFG` and `selectionfg`
- Organize configuration entries alphabetically for better maintainability
- Choose descriptive file names like `hx_launcher.sh` instead of generic names like `hx`
- Use explicit long-form syntax like `[language-server.<name>]` for clarity

Inconsistent naming creates confusion, makes code harder to maintain, and can lead to subtle bugs when identifiers don't match their expected format.

---

## Environment-specific error handling

<!-- source: prettier/prettier | topic: Error Handling | language: JavaScript | updated: 2025-02-26 -->

Separate development-time assertions from production error handling based on the runtime environment. Development assertions should be used to catch programming errors and validate internal assumptions during development, while production code should focus on graceful error handling with meaningful user-facing messages.

Use environment checks to conditionally enable development assertions:

```js
const assertComment = process.env.NODE_ENV === "production" 
  ? noop 
  : function(comment, text) {
      if (!isLineComment(comment) && !isBlockComment(comment)) {
        throw new TypeError(`Unknown comment type: "${comment.type}".`);
      }
    };

// In production, provide simple validation with clear messages
if (!isLineComment(comment) && !isBlockComment(comment)) {
  throw new TypeError(`Unknown comment type: "${comment.type}".`);
}
```

This approach allows comprehensive debugging during development while maintaining clean, user-friendly error handling in production. Configure your build system to remove development-only assertions rather than replacing them with verbose conditional checks that add unnecessary complexity to the codebase.

---

## Centralize configuration management

<!-- source: ghostty-org/ghostty | topic: Configurations | language: Swift | updated: 2025-02-25 -->

Avoid hardcoded or duplicated configuration values by centralizing them in a dedicated location. When configurations are needed across multiple components, extract the logic for accessing and applying them so it can be reused. This prevents inconsistencies when configurations change and makes the codebase more maintainable.

**Instead of this:**
```swift
private enum WindowConfig {
    static let defaultSize = CGSize(width: 800, height: 600)
}
```

**Do this:**
```swift
// In a centralized configuration file/class
struct WindowConfigManager {
    func getDefaultSize(from config: AppConfig) -> CGSize {
        // Extract from config or fallback to default
        return CGSize(
            width: config.windowWidth ?? 800,
            height: config.windowHeight ?? 600
        )
    }
}

// When using the configuration
let windowSize = windowConfigManager.getDefaultSize(from: appConfig)
```

This approach ensures configurations are managed consistently, prevents duplicate values across the codebase, and makes it easier to update configuration behavior in one place.

---

## Documentation example consistency

<!-- source: prettier/prettier | topic: Code Style | language: Markdown | updated: 2025-02-22 -->

Ensure all code examples and documentation maintain consistent formatting standards, use descriptive variable names, and apply proper syntax highlighting. This includes using meaningful identifiers instead of cryptic names like `a60`, applying correct language tags for syntax highlighting (e.g., `css` instead of `jsx` for CSS code), and providing clear examples rather than error messages when demonstrating new features.

Examples of good practices:
- Use descriptive names: `something` instead of `a60` for imports
- Apply proper syntax highlighting: ```css for CSS code, ```ts for TypeScript
- Show working examples: `import { type A } from "mod";` instead of syntax error messages
- Maintain consistent command formats: `yarn exec prettier` across all documentation
- Use proper JSDoc formatting: `/** @type {import("prettier").Options} */`

This consistency helps developers understand features more clearly and maintains professional documentation standards across the entire codebase.

---

## Graceful error recovery

<!-- source: vercel/turborepo | topic: Error Handling | language: Other | updated: 2025-02-21 -->

Implement error handling that accumulates diagnostics rather than failing immediately, especially for operations that could help users identify and fix problems. Design systems to continue functioning when possible, with configurable strictness levels.

For diagnostic operations like queries or validation, prioritize providing useful information even when errors exist. This helps users understand and fix issues rather than blocking them entirely.

Example implementation pattern:
```go
// Instead of immediately failing on first error
if err != nil {
  return fmt.Errorf("invalid task configuration: %w", err)
}

// Use a diagnostic collector approach
diagnostics := &DiagnosticCollector{}
if err != nil {
  diagnostics.Add(Diagnostic{
    Severity: Error,
    Message: fmt.Sprintf("invalid task configuration: %s", err),
  })
}

// Only fail immediately for critical errors or in execution mode
if !queryMode && diagnostics.HasErrors() {
  return diagnostics.Error()
}

// Otherwise, continue with as much functionality as possible
// but include warnings about the issues
return result, diagnostics.Warnings()
```

Consider providing configuration options for users to control error behavior, such as the `--continue` flag with values like "none", "independent-tasks-only", or "all" to specify which operations should continue when errors occur.

---

## Write audience-appropriate documentation

<!-- source: alacritty/alacritty | topic: Documentation | language: Markdown | updated: 2025-02-20 -->

Documentation should be written from the perspective of its intended audience, using language and detail levels appropriate for that audience. Focus on what matters most to the reader rather than technical implementation details.

For user-facing documentation (changelogs, READMEs, FAQs):
- Describe effects and outcomes rather than internal mechanisms
- Avoid vague terms like "could", "easily", or "might" 
- Keep explanations concise and practical
- Highlight information that requires user attention (e.g., breaking changes)

For developer documentation:
- Use precise, unambiguous language
- Distinguish between different types of users (end users vs library consumers)
- Ensure grammatical correctness and clarity

Example from changelog entries:
```
❌ Technical: "Shell initialization on macOS to manually check the ~/.hushlogin file"
✅ User-focused: "Hide login message if ~/.hushlogin is present"

❌ Vague: "could be easily done by user"  
✅ Precise: "can be done outside of alacritty_terminal"
```

This approach ensures documentation serves its intended purpose by meeting readers where they are and providing the information they actually need.

---

## preserve exception causes

<!-- source: bazelbuild/bazel | topic: Error Handling | language: Java | updated: 2025-02-20 -->

When catching an exception and re-throwing a different exception type, always preserve the original exception as the cause. This maintains the full stack trace and context, making debugging significantly easier.

Swallowing the original exception by not setting it as a cause breaks the error chain and hides valuable debugging information about the root cause of the failure.

**Bad:**
```java
try {
  return Long.parseUnsignedLong(string);
} catch (NumberFormatException e) {
  throw new ParseException("identifier is too large");  // Lost original cause!
}
```

**Good:**
```java
try {
  return Long.parseUnsignedLong(string);
} catch (NumberFormatException e) {
  throw new ParseException("identifier is too large", e);  // Preserves cause
}
```

For custom exceptions that don't accept a cause parameter, use `initCause()`:
```java
try {
  // some operation
} catch (IOException e) {
  CustomException custom = new CustomException("operation failed");
  custom.initCause(e);
  throw custom;
}
```

This practice is especially important in complex systems where exceptions may be caught and re-thrown multiple times through different layers, as each layer can add context while preserving the original root cause.

---

## Document cache strategies

<!-- source: vercel/turborepo | topic: Caching | language: Other | updated: 2025-02-19 -->

{% raw %}
Always provide clear documentation and implementation for caching strategies, including key generation, invalidation policies, and default behaviors. When implementing caching:

1. Choose appropriate cache keys that balance specificity and reusability:
   - For CI environments, consider using commit SHA with restore-keys fallback:
   ```yaml
   - uses: actions/cache@v4
     with:
       path: .turbo
       key: ${{ runner.os }}-turbo-${{ github.sha }}
       restore-keys: |
         ${{ runner.os }}-turbo-
   ```

2. Document cache configuration options explicitly:
   - Explain what happens when cache configuration is missing
   - Specify available cache sources and their permissions (e.g., local vs. remote)
   - Describe the behavior of cache invalidation

3. Make cache behavior predictable and configurable:
   - Allow users to control cache sources (e.g., `--cache=local:rw,remote:r`)
   - Provide clear indicators when caching is enabled/disabled
   - Document which artifacts will be cached by default

Proper cache strategy documentation prevents unexpected behavior, improves performance, and gives users control over how and where their data is cached.
{% endraw %}

---

## Identifier Naming Consistency

<!-- source: mermaid-js/mermaid | topic: Naming Conventions | language: JavaScript | updated: 2025-02-18 -->

Use naming that is explicit, consistent, and self-describing.

Rules:
- Avoid magic strings for statement/type/keyword values: create named constants (and reuse them).
- Avoid abbreviations; prefer meaningful, intention-revealing names (e.g., `today`, `midnightDate`).
- Enforce a single identifier style for externally referenced keys/names (e.g., choose kebab-case everywhere; don’t support both camelCase and kebab-case).
- Standardize patterned generated IDs via a shared helper/function, and use template literals for readability.
- Prefer named constructs over index-based ones (e.g., named capture groups instead of `untilStatement[1]`).

Example:
```js
// Named constants (avoid magic strings)
export const STMT_STATE = 'state';
export const STMT_DIR = 'dir';

function getDirection(rootDoc) {
  const doc = rootDoc.find((d) => d.stmt === STMT_DIR);
  return doc;
}

// Shared ID generator (consistent IDs)
export const getEdgeId = (from, to, { counter = 0 } = {}) =>
  `edge_${from}_${to}_${counter}`;

// Named capture groups (clarity)
const match = /^until\s+(?<ids>[\d\w- ]+)/.exec(str);
if (match) {
  for (const id of match.groups.ids.split(' ')) {
    // ...
  }
}
```

Apply these consistently across the codebase to reduce confusion, prevent subtle mismatches (like casing), and make identifiers easier to search, understand, and maintain.

---

## Use functional null handling

<!-- source: vercel/turborepo | topic: Null Handling | language: Rust | updated: 2025-02-18 -->

Leverage Rust's functional operators for handling nullable and optional values. Instead of using unwrap() or explicit if-statements, prefer combinators like ok(), and_then(), map_or_else() and the ? operator with Option types. This leads to more concise, readable, and null-safe code:

```rust
// Instead of this:
let package_manager = PackageJson::load(&base.repo_root.join_component("package.json"))
    .and_then(|package_json| {
        Ok(PackageManager::read_or_detect_package_manager(
            &package_json,
            &base.repo_root,
        ))
    })
    .map_or_else(|_| "Not found".to_owned(), |pm| pm.unwrap().to_string());

// Prefer this:
let package_manager = PackageJson::load(&base.repo_root.join_component("package.json"))
    .ok()
    .and_then(|package_json| {
        PackageManager::read_or_detect_package_manager(&package_json, &base.repo_root).ok()
    })
    .map_or_else(|| "Not found".to_owned(), |pm| pm.to_string());

// Instead of this:
if self.commits.is_empty() {
    return None;
}
if let Some(first_commit) = self.commits.first() {
    let id = &first_commit.id;
    return Some(format!("{id}^"));
}

// Prefer this:
let first_commit = self.commits.first()?; 
let id = &first_commit.id;
Some(format!("{id}^"))
```

Additionally, prefer using Option<T> over returning default values for nullable fields. This makes the absence of a value explicit at the type level and forces consumers to handle both cases appropriately.

---

## YAML-first config schema

<!-- source: mermaid-js/mermaid | topic: Configurations | language: Markdown | updated: 2025-02-15 -->

When adding or changing configurable behavior, define it in the correct config scope and expose it via YAML/frontmatter—don’t introduce new diagram-specific syntax/directives, and don’t place diagram-only options in global config.

**Rules**
1. **Use the diagram’s config schema for diagram-specific options** (the main/global config should not receive diagram-only variables). Keep docs consistent with the generated schema.
2. **Model nested configuration as nested objects** (e.g., `elk.nodePlacement.strategy` is an object path). Avoid ambiguous/flat structures that don’t match the existing nesting patterns.
3. **Prefer YAML/frontmatter over new custom keywords or deprecated directives**. If a feature needs configuration, make it a YAML `config:` entry.

**Examples**
- Replace deprecated directive with YAML frontmatter:
```markdown
---
config:
  markdownAutoWrap: false
---
```
- Move Gantt “working hours” from new syntax into YAML config:
```markdown
---
title: A Gantt Diagram
config:
  gantt:
    dateFormat: YYYY-MM-DD
    workdayStartTime: 08:00
    workdayEndTime: 17:00
---

gantt
  %% gantt content ...
```

Apply these rules for each new option so it has a single source of truth (schema), a clear location (scope), and a consistent user-facing configuration mechanism (YAML).

---

## Protect shared state

<!-- source: wavetermdev/waveterm | topic: Concurrency | language: Go | updated: 2025-02-13 -->

Ensure mutable shared data is never exposed or accessed without explicit synchronization. When data crosses goroutine boundaries you must either copy it, provide a concurrency-safe accessor that returns a snapshot, or protect it with proper synchronization (mutexes, atomics, or reference counting). This prevents races when marshaling, iterating, or doing read-modify-write updates.

Guidelines (practical):
- Return copies for internal maps/structs or provide an accessor that returns a copied snapshot. e.g.:
  func (m *MShellProc) GetRemoteRuntimeState() RemoteRuntimeState {
      varsCopy := make(map[string]string)
      for k,v := range m.Remote.StateVars { // hold m lock while reading
          varsCopy[k] = v
      }
      state.RemoteVars = varsCopy
      return state
  }
- Do not expose internal mutable slices/maps directly. If an API must iterate over a collection that is guarded by a lock, provide a locked copy for iteration (avoid iterating over the locked map). Use helper methods like remote.GetRemoteMap() that return a copy.
- Protect read-modify-write operations (e.g., append/offset updates) with a lock or an atomic protocol. If an operation must be atomic across multiple fields, hold the mutex for the entire operation.
- Use reference counting or equivalent coordination when cache entries or resources may be concurrently flushed and used. Only remove/zero resources when ref count is zero and hold the lock while updating refs.
- Make channel ownership explicit: only the sender should close a channel. Do not attempt to close a channel from a receiver. If draining with a timeout, avoid hiding ownership errors—fail fast or document panic behavior deliberately.
- Prefer fail-fast when unexpected contention indicates a logic error (e.g., file-create flock): return an error immediately rather than silently waiting.
- Choose callbacks vs channels deliberately: callbacks are lightweight and can capture closures but will run inline and block the caller; channels can decouple execution and allow concurrency but add complexity. Document blocking behavior and ensure caller expectations are clear.

Why: these rules address several recurring concurrency bugs in our codebase—races caused by sharing internal state (maps/slices), races when updating file offsets or cache entries concurrently, unsafe iteration over maps, incorrect channel closing, and hidden blocking. Applying them reduces data races, unexpected panics, and subtle bugs during marshaling or concurrent operations.

Quick patterns:
- Safe accessor that returns snapshot: provide function that locks, copies, unlocks, return copy.
- Refcount pattern for cache entry:
  entry.Lock.Lock()
  entry.Refs++
  entry.Lock.Unlock()
  // use entry
  entry.Lock.Lock()
  entry.Refs--
  if entry.Refs == 0 && shouldRemove { remove }
  entry.Lock.Unlock()

References: [0,1,2,3,4,5,6,7]

---

## Semantic naming conventions

<!-- source: vercel/turborepo | topic: Naming Conventions | language: TypeScript | updated: 2025-02-13 -->

Use names that clearly convey the purpose and content of variables, parameters, and properties. When working with objects, always access specific properties rather than using the object directly in string operations to prevent "[object Object]" outputs. Include proper type declarations for parameters that describe their structure.

Example:
```typescript
// Incorrect
function replacePackageManager(packageManager, text) {
  const updatedText = match.replace(replacementRegex, `${packageManager} run`);
  // Results in "[object Object] run"
}

// Correct
function replacePackageManager(packageManager: { name: string }, text: string): string {
  const updatedText = match.replace(replacementRegex, `${packageManager.name} run`);
  // Results in "npm run" or similar
}

// Improved parameter naming
affectedPackages(
  files: Array<string>,
  base?: string | undefined | null, // "base" clearly indicates this is the base commit for comparison
)
```

Choose parameter names that use domain-specific terminology where appropriate to make code more self-documenting and easier to understand.

---

## Cache correctness validation

<!-- source: prettier/prettier | topic: Caching | language: JavaScript | updated: 2025-02-12 -->

Ensure caching implementations store the correct data and use appropriate strategies for the context. Cache should store the final processed output, not intermediate or input data, and should include strategy options for different security/performance requirements.

Key considerations:
- **Store processed output**: Cache the formatted result, not the original input. When using `--write` flag, cache the formatted content, not the unformatted input.
- **Provide strategy options**: Implement both metadata-based (faster) and content-based (more secure) caching strategies, similar to ESLint's `--cache-strategy` option.
- **Handle format changes gracefully**: When cache format changes between versions, detect incompatible formats and recreate the cache rather than throwing errors.
- **Validate cache usage context**: Ensure cache is not used inappropriately (e.g., don't cache stdin input, verify cache matches current options).

Example implementation:
```javascript
// Good: Store formatted output and handle strategy
if (isCacheExists && cacheStrategy === "content") {
  result = { formatted: input };
} else {
  result = format(context, input, options);
  // Cache the formatted result, not the input
  formatResultsCache?.setFormatResultsCache(filename, result.formatted, options);
}

// Good: Handle cache format changes
try {
  this.#fileEntryCache = fileEntryCache.createFromFile(cacheFileLocation, useChecksum);
} catch {
  // If cache format changed, delete and retry
  fs.unlinkSync(cacheFileLocation);
  this.#fileEntryCache = fileEntryCache.createFromFile(cacheFileLocation, useChecksum);
}
```

This ensures cache reliability and prevents subtle bugs where cached data doesn't match expected output.

---

## cache invalidation strategy

<!-- source: prettier/prettier | topic: Caching | language: Markdown | updated: 2025-02-12 -->

Implement comprehensive cache invalidation mechanisms that automatically handle format changes between versions while providing clear manual removal options. When cache formats change, automatically detect and remove incompatible cache files to prevent runtime errors. Additionally, document cache locations and provide accurate removal commands for manual cache management.

For automatic invalidation, check cache format compatibility on startup:
```bash
# Cache format changed in version 3.5, remove old cache to prevent crashes
if (cacheFormatVersion !== currentVersion) {
  removeOutdatedCache();
}
```

For manual removal, provide precise documentation with correct command syntax:
```bash
# Remove cache manually (note: no -f flag to show errors if file not found)
rm ./node_modules/.cache/prettier/.prettier-cache
```

This approach prevents crashes from incompatible cache formats while giving users clear guidance for manual cache management when needed.

---

## Ensure semantic naming accuracy

<!-- source: prettier/prettier | topic: Naming Conventions | language: TypeScript | updated: 2025-02-10 -->

Names should accurately reflect the actual behavior, constraints, and purpose of the code element they represent. Misleading names create confusion and make code harder to understand and maintain.

**Key principles:**
- Interface names should match their property requirements (e.g., avoid naming an interface `RequiredOptions` if it contains optional properties)
- Type names should clearly communicate their actual constraints and behavior
- Method and property names should consistently reflect their access patterns

**Example of problematic naming:**
```typescript
// Misleading - contains optional properties despite "Required" in name
export interface RequiredOptions {
  singleAttributePerLine: boolean;
  jsxBracketSameLine?: boolean; // Optional property in "Required" interface
}
```

**Better approach:**
```typescript
// Clear and accurate naming
export interface FormattingOptions {
  singleAttributePerLine: boolean;
  jsxBracketSameLine?: boolean;
}

// Or separate required vs optional
export interface RequiredFormattingOptions {
  singleAttributePerLine: boolean;
}
export interface OptionalFormattingOptions {
  jsxBracketSameLine?: boolean;
}
```

When reviewing code, ask: "Does this name accurately describe what this element actually does or contains?" Names that contradict their implementation create technical debt and developer confusion.

---

## Explicit, organized code

<!-- source: wavetermdev/waveterm | topic: Code Style | language: TypeScript | updated: 2025-02-09 -->

Write code that is explicit, predictable, and organized to improve readability and avoid subtle bugs.

What to do:
- Make control flow explicit. In switch statements and other control structures always use break/return/continue as appropriate. If fallthrough is intentional, annotate it with a clear comment or a lint directive (e.g. // fallthrough). Example (fix missing break):
  switch (action.type) {
    case LayoutTreeActionType.ReplaceNode: {
      // ...handle replace...
      break; // prevent accidental fallthrough
    }
    case LayoutTreeActionType.SplitHorizontal: {
      // ...handle split...
      break;
    }
  }

- Avoid redundant calls and duplicate side-effects. Trust single-responsibility helpers and do not repeat work already performed by a called method. If a method already sets state, do not call the setter again. Example (remove duplication):
  openAIAssistantChat(): void {
    this.setActiveAuxView(appconst.InputAuxView_AIChat);
    // don't also call this.setAuxViewFocus(true) if setActiveAuxView already sets focus
  }

- Organize runtime values and small types where they belong. Place enums, constants, and small runtime-bound types close to the code that uses them unless there's a strong reason to centralize them. If you move a value to a shared file, document why (runtime usage, reuse across modules).

Why this matters:
- Explicit control flow prevents accidental bugs from fallthrough and makes intent clear.
- Removing redundant calls reduces unexpected state changes and simplifies reasoning about code.
- Colocating related runtime values improves discoverability and keeps code meaningfully grouped.

When in doubt, prefer clarity: add a short comment explaining non-obvious choices (intentional fallthrough, why a value is placed in a shared file, or why a duplicate call remains).

---

## Restrict server access

<!-- source: vitejs/vite | topic: Security | language: Markdown | updated: 2025-02-07 -->

Always configure server security settings with explicit allowed lists rather than permissive values. Using `true` for settings like `server.allowedHosts` or `server.cors` creates serious security vulnerabilities by allowing any website to access your development server through DNS rebinding attacks, potentially exposing source code and sensitive content.

```js
// INSECURE: Don't do this
export default defineConfig({
  server: {
    allowedHosts: true,  // Allows any host to access your server
    cors: true  // Allows any origin to make requests
  }
})

// SECURE: Do this instead
export default defineConfig({
  server: {
    allowedHosts: ['myapp.local', '.example.com'],  // Only specific hosts
    cors: {
      origin: ['https://trusted-site.com']  // Only specific origins
    }
  }
})
```

Only add domains you control to these allowlists, and never add Top-Level Domains like `.com`. This protection is especially important for development servers where authentication might be disabled or less restrictive.

---

## Use network timeouts

<!-- source: wavetermdev/waveterm | topic: Networking | language: Go | updated: 2025-02-06 -->

Ensure all network operations are cancellable, timeout-protected, and executed where the resource lives.

Motivation
- Network calls can hang, run on the wrong machine, or transfer too much data. Apply consistent patterns to avoid resource leaks, unresponsive reads, and incorrect behavior when operating on remote resources.

Rules
1) Always use context and timeouts for outbound network calls and dials. Use context-aware APIs (DialContext, http.NewRequestWithContext) and set sensible connect/read timeouts.
   Example (HTTP):
   ctx, cancel := context.WithTimeout(parentCtx, 10*time.Second)
   defer cancel()
   req, _ := http.NewRequestWithContext(ctx, "POST", url, body)
   resp, err := http.DefaultClient.Do(req)

   Example (websocket dial):
   d := websocket.Dialer{HandshakeTimeout: 20 * time.Second}
   conn, _, err := d.DialContext(ctx, wsURL, nil)

2) Make long-running reads cancellable by closing the underlying connection from another goroutine when the context expires. Closing the socket unblocks ReadMessage/Read calls so goroutines don’t leak.
   Example:
   go func() {
       <-ctx.Done()
       conn.Close()
   }()

3) Prefer incremental transfers for streaming channels: send only new/changed messages instead of replaying entire history to reduce bandwidth and contention on shared websockets. If a timeout happens, send a clear partial/final packet (e.g., a timeout or summary packet) so the client retains what it already received.

4) Execute resource-heavy or resource-local operations on the side that owns the resource (server-side) when invoked remotely. For example, create zip archives of a server’s config on the server and then copy the resulting artifact to the client (via filestore/WFS or an explicit transfer), rather than trying to reconstruct the server’s environment on the client.

5) Preserve transport/URI semantics when parsing and serializing (e.g., trailing slashes) so network requests behave as expected.

When to revisit
- If a read goroutine still blocks despite closing the connection, re-check use of non-cancellable APIs; prefer context-aware libraries. Tune timeout values based on operation type (short for quick checks like release queries, longer for large uploads/streams).

References: discussions 0,1,2,3,4,5

---

## Specify API contracts

<!-- source: wavetermdev/waveterm | topic: API | language: Go | updated: 2025-02-06 -->

State and document explicit, unambiguous contracts for all API endpoints and RPC messages, especially around resource identity, data encoding, and file-operation semantics. Motivation: inconsistent assumptions about where a path comes from, whether payloads are encoded, and what ReadAt/WriteAt should return lead to brittle clients and surprising server behavior. How to apply:

- Resource identity in URLs: treat resources as RESTful paths when they represent server resources. Put file/config paths in the URL path segment rather than opaque query params so clients can request /config/keybindings.json or /files/{bucket}/{object}. Example: change

  // avoid reading resource from query
  qvals := r.URL.Query()
  filePath := qvals.Get("path")

  // prefer extracting from URL path (mux param or path prefix)
  // e.g. GET /config/{path}
  filePath := mux.Vars(r)["path"]

- Encoding contracts: document and enforce how binary data is transported. If a field is named data64, require base64 encoding at the producer side and decode at the consumer side. Make encoding explicit in code:

  // when producing file chunks
  chunk := buf[:n]
  resp.Data64 = base64.StdEncoding.EncodeToString(chunk)

  // when consuming
  data, err := base64.StdEncoding.DecodeString(resp.Data64)

- File operation semantics: define and document behavior for reads/writes with offsets. Choose one of these and be consistent:
  - Strict: return an error when WriteAt offset > file size (simple, predictable).
  - Sparse-supporting: allow writes past EOF by implicit zero-padding, but document performance implications and whether padding bytes count toward returned bytesWritten.

  If sparse writes are supported, prefer these rules: pad only as needed (e.g., block-level padding to avoid huge copies), do not include implicit padding bytes in the bytesWritten return value (return only the number of user bytes written), and ensure ReadAt returns zeros for any uninitialized region within the logical file range. Example contract: "WriteAt will left-pad up to MaxBlockSize in-memory for efficiency; returned bytesWritten excludes implicit zeros. ReadAt will return logical zeros for uninitialized regions within the file length."

- Responsibility boundaries: document which side normalizes/validates paths and who encodes/decodes payloads. For non-URL path formats acceptible to client libraries, document helper functions and keep server endpoints stable. Example: FileReadCommand should pass a well-formed FileData with Info.Path when the fileshare client is expected to own normalization:

  data, err := wshclient.FileReadCommand(RpcClient, wshrpc.FileData{Info: &wshrpc.FileInfo{Path: fmt.Sprintf(pattern, oid, fname)}}, ...)

- API surface ergonomics: prefer small, explicit signatures for public APIs. Use variadic parameters for option lists or alias checks (e.g., CheckOptionAlias(aliases ...string)) and avoid overusing generics where a simple interface suffices. Provide convenience helpers for common behaviors (e.g., SetInteractive(update, bool)).

Checklist for reviewers and implementers:
- Does the endpoint identify resources via path segments when appropriate? (discussion 0)
- Is there a documented encoding contract for binary fields (data64/base64)? Does code encode before setting and decode on receipt? (discussion 1)
- Are read/write offset semantics documented and consistent (error vs sparse write; returned byte counts)? (discussion 4)
- Are responsibilities for normalization and output modes clear between client and server? (discussions 2,3)
- Are API signatures simple and explicit; use variadic helpers when it improves clarity? (discussions 5,6)

Following these rules reduces surprises for clients, avoids implicit assumptions, and makes APIs easier to evolve and document.

---

## Documentation clarity standards

<!-- source: prettier/prettier | topic: Documentation | language: Markdown | updated: 2025-02-04 -->

Ensure documentation is clear, precise, and technically accurate to prevent confusion and build errors. This includes proper escaping of special characters, consistent terminology, version-specific accuracy, and unambiguous language.

Key practices:
- Escape HTML tags in markdown or wrap them in backticks to prevent parsing errors
- Use consistent terminology throughout (e.g., "MDX v2" not "MDX 2")
- Provide version-specific information when features or paths change between releases
- Choose precise words that reduce ambiguity (e.g., "unless specified" instead of "not specified")
- Add clarifying punctuation like quotes around file names when context could be confusing
- Define technical terms when they might be unfamiliar to readers

Example of proper escaping:
```markdown
<!-- Problematic -->
#### Handle <style> and <pre> tags in Handlebars/Glimmer

<!-- Better -->
#### Handle `<style>` and `<pre>` tags in Handlebars/Glimmer
```

Example of version-specific clarity:
```markdown
<!-- Vague -->
- ES modules: `standalone.mjs`, starting in version 2.2

<!-- Clear -->
- ES modules: `standalone.mjs`, starting in version 3.0 (In version 2, `esm/standalone.mjs`.)
```

This prevents build failures, reduces reader confusion, and maintains professional documentation standards.

---

## organize code structure

<!-- source: electron/electron | topic: Code Style | language: TypeScript | updated: 2025-02-04 -->

Make deliberate structural decisions that improve code maintainability and readability. Consider the appropriate implementation layer, proper encapsulation patterns, and logical organization of code components.

Key principles:
- Use truly private functions instead of underscore-prefixed "private" methods to avoid abuse: `function awaitNextLoad(...` instead of `WebContents.prototype._awaitNextLoad`
- Choose the optimal implementation layer for maintainability - move logic to C++ when it reduces code spread across files and improves efficiency
- Organize tests logically with descriptive names rather than excessive nesting: `it('returns image with requested size when both dimensions are bigger', async () => {` instead of multiple nested `describe` blocks
- Prioritize fewer files with clearer responsibilities over scattered implementations

Example of proper encapsulation:
```typescript
// Instead of:
WebContents.prototype._awaitNextLoad = function (navigationUrl: string) {
  // implementation
}

// Use:
function awaitNextLoad(navigationUrl: string) {
  // implementation
}
// Then call with: return awaitNextLoad.call(this)
```

This approach reduces code complexity, improves maintainability, and makes the codebase easier to navigate and understand.

---

## Gate UI features

<!-- source: likec4/likec4 | topic: Configurations | language: TSX | updated: 2025-02-01 -->

Ensure UI elements (buttons, icons, tooltips, overlays) are only registered or rendered when the corresponding configuration or feature flag is enabled. Also ensure feature flags are passed into components or a central store so components make rendering decisions from configuration rather than hard-coded assumptions.

Motivation
- Prevents exposing unavailable features, avoids UI clutter, and keeps behavior predictable across environments.
- Matches existing patterns where flags are passed from top-level props into stores/components.

How to apply
1. Propagate flags: accept feature flags as props at top-level components and pass them into your UI components or into the app/store.
   Example pattern (top-level):
   // LikeC4Diagram.tsx (pattern reference)
   <LikeC4Diagram enableSearch={enableSearch} />

2. Gate registration: only add buttons/actions to arrays when the flag is true.
   Example:
   const buttons = []
   if (flags.enableVscode) {
     buttons.push({
       id: 'open-in-vscode',
       label: 'Open in VSCode',
       onClick: () => { /* ... */ },
     })
   }

3. Gate rendering: only render optional UI elements in JSX when the flag is true or derived from the store/props.
   Example:
   <ActionIconGroup>
     {flags.enableSearch && (
       <Tooltip label="Search">
         <ActionIcon>/* icon */</ActionIcon>
       </Tooltip>
     )}
   </ActionIconGroup>

Notes
- Prefer a single source of truth for flags (props -> context/store) to avoid mismatches.
- Keep gating logic simple and colocated with the registration or render site so it's obvious why an element may be absent.
- Include tests or story variants for both enabled and disabled states to prevent regressions.

---

## API backwards compatibility

<!-- source: python-poetry/poetry | topic: API | language: Python | updated: 2025-01-30 -->

When evolving public APIs, prioritize backwards compatibility through proper deprecation strategies and careful interface design. Avoid breaking changes by using overloads, deprecation warnings, and gradual migration paths.

Key principles:
- Use method overloads to maintain existing signatures while adding new functionality
- Keep implementation details private to avoid coupling external code to internal changes  
- Deprecate old parameters/methods before removing them, providing clear migration paths
- Consider the impact on plugins and external consumers when making API changes

Example approach for adding new parameters:
```python
def add_repository(
    self,
    repository: Repository,
    priority: Priority = Priority.PRIMARY,
    # Keep old parameters for backwards compatibility
    default: bool = False, 
    secondary: bool = False
) -> None:
    # Handle both old and new parameter styles
    if default or secondary:
        warnings.warn("default/secondary parameters are deprecated, use priority instead")
```

This ensures external code continues working while providing a clear upgrade path. Always weigh the benefits of cleaner APIs against the cost of breaking existing integrations.

---

## explicit configuration specification

<!-- source: python-poetry/poetry | topic: Configurations | language: Markdown | updated: 2025-01-29 -->

Always explicitly specify configuration values rather than relying on defaults or implicit behavior. Poetry requires unambiguous configuration to function correctly, and many issues arise from incomplete or assumed specifications.

Key areas requiring explicit specification:

**Version Constraints**: Explicitly declare Python version requirements and dependency constraints. If using both `project.requires-python` and `tool.poetry.dependencies.python`, ensure the Poetry specification is a subset of the project specification.

```toml
[project]
requires-python = ">=3.8"

[tool.poetry.dependencies]
python = "^3.8"  # Must be subset of project.requires-python

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]  # Include version constraints
```

**Build Dependencies**: Assume only Python built-ins are available in build environments. Explicitly declare all required packages, including common ones like `setuptools`.

```toml
[build-system]
requires = ["poetry-core", "setuptools", "cython"]  # Don't assume setuptools is available
```

**Repository Sources**: Explicitly configure package source priorities and constraints to avoid dependency confusion attacks. Omit URLs for PyPI when configuring it explicitly.

```toml
[[tool.poetry.source]]
name = "pypi"
priority = "primary"  # No URL needed for PyPI

[[tool.poetry.source]]
name = "private-repo"
url = "https://private.example.com/simple/"
priority = "explicit"
```

**CLI Usage**: Use `--` to terminate option parsing when values might start with hyphens, and specify full paths or explicit options rather than relying on defaults.

```bash
poetry config http-basic.repo token -- ${TOKEN}  # Prevent parsing issues
```

This approach prevents configuration ambiguity, reduces debugging time, and ensures consistent behavior across different environments and Poetry versions.

---

## defensive nil handling

<!-- source: wavetermdev/waveterm | topic: Null Handling | language: Go | updated: 2025-01-22 -->

Always validate values and short-circuit on errors; guard uses of possibly nil/empty values while avoiding redundant checks when types guarantee non-nil.

Motivation:
- Prevent nil-pointer dereferences and logic bugs by validating inputs and return early on errors.
- Only add nil checks where the value may be absent/untrusted; don’t clutter code with checks that duplicate the type/API contract.
- Prefer correct, non-indirected types (e.g., []byte) to reduce nil-handling complexity.

Practices to follow:
- Validate external/untrusted inputs and parse results before use and return early on error.
  Example: check parse errors and avoid using a possibly nil value:

  // wrong: may deref newPk when parsing failed
  newPk, rtnErr := EvalMetaCommand(ctxWithHistory, pk)
  if rtnErr == nil {
      update, rtnErr = HandleCommand(ctxWithHistory, newPk)
  }

  // correct: short-circuit on error
  newPk, rtnErr := EvalMetaCommand(ctxWithHistory, pk)
  if rtnErr != nil {
      return nil, rtnErr
  }
  update, rtnErr = HandleCommand(ctxWithHistory, newPk)

- Guard resource operations that may be nil (files, sockets, interfaces) before calling methods like Close.
  Example:

  defer func() {
      for _, extraFile := range cw.Cmd.ExtraFiles {
          if extraFile != nil {
              extraFile.Close()
          }
      }
  }()

- Validate numeric/string inputs (use helpers) to enforce expected ranges and avoid later checks:
  Example: use a helper for positive integers

  idx, err := resolvePosInt(newScreenIdxStr, 1)
  if err != nil {
      return nil, err
  }

- Prefer using slices directly instead of pointers to slices; a nil slice expresses absence without extra indirection.
  Example: use sudoPw []byte instead of sudoPw *[]byte

- Do not add nil checks when the API/type guarantees non-nil; rely on that contract to keep code clear. If the contract changes or is unclear, update the type or document it rather than peppering checks.

When in doubt, ask: is the value coming from external/untrusted input or can it legitimately be nil? If external or ambiguous: validate and short-circuit. If internal and the type guarantees non-nil: omit redundant checks.

References: discussions [0,2,3,4,5,1]

---

## Avoid exposing sensitive APIs

<!-- source: electron/electron | topic: Security | language: Markdown | updated: 2025-01-19 -->

Do not enable configurations that expose Node.js or Electron APIs to untrusted web content in renderer processes. This includes avoiding `nodeIntegration: true` for remote content and not directly exposing IPC APIs in preload scripts.

**Why this matters:**
- Enabling `nodeIntegration: true` disables sandboxing and grants full Node.js access to renderer processes
- Exposing raw APIs like `ipcRenderer.on` gives renderers direct access to the entire IPC event system
- Remote content should never have access to these privileged APIs due to security risks

**Secure approach:**
```js
// ❌ Dangerous - exposes Node.js APIs to remote content
new BrowserWindow({
  webPreferences: {
    nodeIntegration: true, // Disables sandbox, security risk
    contextIsolation: false
  }
})

// ✅ Secure - use sandboxed renderer with controlled API exposure
new BrowserWindow({
  webPreferences: {
    sandbox: true, // Default since Electron 20
    contextIsolation: true, // Default since Electron 20
    preload: path.join(__dirname, 'preload.js')
  }
})

// In preload.js - expose only specific, validated APIs
const { contextBridge, ipcRenderer } = require('electron')

// ❌ Don't expose raw IPC
window.ipcRenderer = ipcRenderer

// ✅ Expose controlled, specific functions
contextBridge.exposeInMainWorld('electronAPI', {
  performAction: (...args) => ipcRenderer.invoke('perform-action', ...args)
})
```

Always validate the origin and content when handling requests from renderer processes, especially when loading remote content. Use the principle of least privilege - only expose the minimum APIs necessary for your application to function.

---

## consistent naming conventions

<!-- source: hyprwm/Hyprland | topic: Naming Conventions | language: Other | updated: 2025-01-18 -->

Follow the project's established naming conventions consistently across all code. Use camelCase for variables, functions, and parameters, avoiding Hungarian notation and snake_case. Apply type-specific prefixes: classes should have a 'C' prefix (e.g., `CXCBConnection`), enums should have an 'e' prefix (e.g., `eAutoDirs`), and enum values should be in CAPS with descriptive prefixes (e.g., `DIR_AUTO_UP`). When possible, wrap standalone functions in appropriate namespaces rather than leaving them in global scope.

Example transformations:
```cpp
// Before
class XCBConnection { };           // Missing C prefix
enum class AutoDirs { auto_up };   // Missing e prefix, snake_case
bool m_benabled;                   // Hungarian notation
void some_function();              // snake_case

// After  
class CXCBConnection { };          // C prefix for classes
enum class eAutoDirs { DIR_AUTO_UP }; // e prefix, CAPS enum values
bool m_enabled;                    // No Hungarian notation
void someFunction();               // camelCase
```

This ensures code readability and maintains consistency with the existing codebase, making it easier for developers to understand type information at a glance and follow established patterns.

---

## Descriptive error messages

<!-- source: electron/electron | topic: Error Handling | language: Other | updated: 2025-01-17 -->

Error messages should be descriptive, contextual, and self-identifying to aid debugging and user understanding. Include relevant context like method names, parameter values, or identifiers that help locate the source of the error.

Key principles:
- Make error messages actionable by suggesting workarounds or next steps when possible
- Include context that identifies where the error originated (method name, component, etc.)
- Add relevant parameter values or identifiers to help with debugging
- Use appropriate logging levels (LOG(ERROR) vs DLOG(ERROR)) based on error severity

Examples:

```cpp
// Poor: Generic error without context
LOG(ERROR) << "Unable to initialize logging from handle.";

// Better: Descriptive with context and actionable guidance
LOG(FATAL) << "Unable to open nul device needed for initialization, aborting startup. "
           << "As a workaround, try starting with --" << switches::kNoStdioInit;

// Poor: Missing context
isolate->ThrowException(v8::Exception::Error(
    gin::StringToV8(isolate, "Unknown error")));

// Better: Self-identifying with context
isolate->ThrowException(v8::Exception::Error(
    gin::StringToV8(isolate, "Failed to retrieve target context for world ID: " + std::to_string(world_id))));

// Poor: Generic error
gin_helper::internal::ReplyChannel::Create(isolate, std::move(callback))
    ->SendError("WebContents does not exist");

// Better: Include channel context for debugging
gin_helper::internal::ReplyChannel::Create(isolate, std::move(callback))
    ->SendError("WebContents does not exist for channel: " + channel);
```

This approach transforms cryptic errors into meaningful diagnostics that developers can act upon, reducing debugging time and improving the overall development experience.

---

## Complete config setting integration

<!-- source: python-poetry/poetry | topic: Configurations | language: Python | updated: 2025-01-15 -->

When adding new configuration settings, ensure they are properly integrated across all required system components. Configuration settings must be registered in multiple locations to function correctly and be discoverable by users.

Required integration points include:
- Default values in the main config class
- Normalizer functions for validation/transformation  
- Command-specific config value lists for discoverability
- User-facing documentation and help text

Example of complete integration:
```python
# In Config class defaults
"max-retries": 0,

# In _get_normalizer method  
"max-retries": lambda val: int(val) if val is not None else 0,

# In ConfigCommand.unique_config_values
"max-retries",
```

Additionally, prefer user-facing configuration options over hidden implementation details. When deprecating config keys, use explicit user warnings rather than developer-only deprecation warnings, as these changes directly impact end users.

This systematic approach prevents incomplete configuration implementations that can lead to runtime errors, inconsistent behavior, or poor user experience when settings are partially recognized by the system.

---

## Design for testability

<!-- source: vercel/turborepo | topic: Testing | language: TypeScript | updated: 2025-01-14 -->

Extract complex logic into separate, pure functions to improve testability. Functions with clear inputs and outputs are easier to test in isolation without complex mocking or setup.

For example, instead of embedding logic directly in larger functions:

```typescript
// Hard to test
export async function transform(args: TransformInput): TransformResult {
  // ...
  // Complex logic embedded in a larger function
  let data = await fs.readFile(readmeFilePath, "utf8");
  const replacements = ['pnpm run', 'npm run', 'yarn run', 'bun run'];
  const replacementRegex = new RegExp(`\\b(?:${replacements.join('|')})\\b`, 'g');
  data = data.replace(replacementRegex, `${selectedPackageManager} run`);
  // ...
}
```

Extract the logic into a testable function:

```typescript
// Easy to test with various inputs
function replacePackageManager(packageManager: string, text: string): string {
  const replacements = ['pnpm run', 'npm run', 'yarn run', 'bun run'];
  const replacementRegex = new RegExp(`\\b(?:${replacements.join('|')})\\b`, 'g');
  return text.replace(replacementRegex, `${packageManager} run`);
}

// Can now be thoroughly tested with parameterized tests
it.each([
  ['npm', '`yarn build`', '`npm run build`'],
  ['pnpm', 'Run `npm start`', 'Run `pnpm run start`'],
  // more test cases...
])('should replace package managers correctly', (packageManager, input, expected) => {
  expect(replacePackageManager(packageManager, input)).toBe(expected);
});
```

This approach makes unit testing straightforward and enables comprehensive test coverage through parameterized test cases.

---

## Targeted yet comprehensive

<!-- source: vitejs/vite | topic: Testing | language: JavaScript | updated: 2025-01-13 -->

Write focused tests that verify specific functionality without unnecessary setup, while still ensuring complete coverage of edge cases. Instead of duplicating complex structures, create minimal test cases that target individual features directly.

Example:
```js
// Instead of copying an entire playground setup
// packages/vite/src/node/__tests__/build.spec.ts
describe('JSON stringify', () => {
  test('tree shaking works correctly', async () => {
    // Minimal test configuration
    const config = { json: { stringify: true } }
    // Test-specific assertions
    const result = await buildWith(config)
    expect(result.hasTreeShaking).toBe(true)
  })
  
  // Include tests for all relevant edge cases
  test('handles file:// protocol', async () => {
    // Add specific test for this protocol
  })
})
```

This approach improves maintainability by keeping tests focused while still ensuring adequate coverage. When adding tests, consider what specific functionality needs verification and create the minimal test setup required, but be thorough in covering variations and edge cases.

---

## Explicit null handling

<!-- source: python-poetry/poetry | topic: Null Handling | language: Python | updated: 2025-01-12 -->

Use explicit and clear patterns when handling null/None values to improve code readability and maintainability. Avoid complex conditional expressions, unnecessary type casting, and ambiguous nullable types.

**Key principles:**

1. **Prefer explicit None checks over complex expressions:**
```python
# Prefer this
if version is None:
    version = packages[0] if packages else None

# Over this  
version = version or packages[0]
```

2. **Use None to mean "unknown" and empty collections for "known empty":**
```python
# Use None when data availability is uncertain
requires_dist = None  # "I don't know what the requirements are"

# Use empty list when you know there are no requirements  
requires_dist = []  # "I know there are no requirements"
```

3. **Use safe access patterns with appropriate defaults:**
```python
# Safe dictionary access
name = poetry.local_config.get("name", "")
headers = kwargs.get("headers", {}) or {}

# Safe attribute checking
if "name" in distribution.metadata:
    name = distribution.metadata["name"]
```

4. **Avoid unnecessary nullable types:**
```python
# Don't make parameters nullable if they're never actually None
def configure_options(self, io: IO) -> None:  # Not IO | None
    # io is always provided by caller
```

5. **Check None conditions first when it's the default case:**
```python
# Put the default/expected case first
if output is None:
    sys.stdout.write(content)
else:
    with open(output, 'w') as f:
        f.write(content)
```

6. **Prefer direct None checks over type casting:**
```python
# Prefer this
if self._cache_control is None:
    return None

# Over this with cast
if self._disable_cache:
    return None
# ... later: cast(CacheControl, self._cache_control)
```

These patterns make null handling intentions clear, reduce the risk of runtime errors, and improve code maintainability by making the expected behavior explicit.

---

## Fail with messages

<!-- source: Homebrew/brew | topic: Error Handling | language: Shell | updated: 2025-01-12 -->

Functions and scripts should never fail silently. When detecting error conditions, always provide clear error messages to stderr that include context about what failed and why, then return an appropriate non-zero exit code. For user-facing commands, include guidance about correct usage when applicable.

Example:
```bash
url_get() {
  if [[ ${#} -eq 0 ]]; then
    echo "Error: url_get requires at least one argument (URL)" >&2
    return 1
  fi
  
  # Function implementation...
}

# Usage with error checking
eval RESULTS=( $(url_get "${URL}" param1 param2) )
if [[ ${#RESULTS[@]} -ne 2 ]]; then
  echo "Error: Failed to parse URL=${URL}!" >&2
  exit 1
fi
```

---

## manage testing dependencies

<!-- source: python-poetry/poetry | topic: Testing | language: Toml | updated: 2025-01-12 -->

Ensure testing dependencies are properly organized, avoid redundancy, and proactively manage unmaintained packages. Place testing-specific dependencies in the correct dependency groups (e.g., `group.test.dependencies` rather than `group.dev.dependencies`). Before adding new testing libraries, verify that existing dependencies don't already provide the same functionality - for example, use `pytest-mock` instead of adding a separate `mock` dependency. Monitor the maintenance status of testing dependencies and plan migration paths for stalled projects.

Example of proper dependency management:
```toml
[tool.poetry.group.test.dependencies]
pytest-httpserver = "^1.0.8"  # Correctly placed in test group
pytest-mock = ">=3.9"         # Use existing mock functionality
# Avoid: mock = "^2.0"         # Redundant with pytest-mock

# Plan migration for unmaintained dependencies
urllib3 = "<2.3"  # Temporary constraint due to httpretty compatibility
# TODO: Migrate from httpretty to mocket for better maintenance
```

This approach maintains a clean, maintainable test infrastructure while avoiding dependency conflicts and technical debt.

---

## Explain code intent

<!-- source: alacritty/alacritty | topic: Documentation | language: Rust | updated: 2025-01-10 -->

Comments and documentation should explain WHY code exists and what purpose it serves, not just describe what the code does. Focus on the reasoning, motivation, and intent behind implementation decisions.

When writing comments, ask yourself: "Would a developer understand the purpose and reasoning behind this code without additional context?" If not, add explanatory comments that clarify the intent.

**Good examples:**
```rust
// Attempt to make the context current, if it is not.
let mut was_context_reset = if is_current {
    false
} else {
    match self.context.make_current(&self.surface) {
        // ... implementation
    }
};
```

```rust
// Windows environment variables require null-terminated strings,
// with a double null at the end to mark the end of the environment block.
result.push(0);
result.push(0);
```

**Avoid comments that just restate the code:**
```rust
// This comment provides no value
// Unsafe because of Windows API calls.
unsafe { /* ... */ }
```

**Instead, explain safety or purpose:**
```rust
// Safe because we verify the handle is valid before dereferencing
unsafe { /* ... */ }
```

This is especially important for complex logic, platform-specific code, non-obvious algorithms, and any code where the implementation strategy might not be immediately clear to future maintainers.

---

## Break down complex functions

<!-- source: vitejs/vite | topic: Code Style | language: TypeScript | updated: 2025-01-10 -->

Improve code readability and maintainability by decomposing large, complex functions into smaller, focused ones. When a function handles multiple responsibilities or becomes difficult to understand at a glance, extract logical parts into well-named helper functions.

For example, instead of a single large function like:

```ts
const getCssTagsForChunk = (chunk, toOutputPath, seen = new Set(), parentImports, circle = new Set()) => {
  const tags = [];
  if (circle.has(chunk)) return tags;
  circle.add(chunk);
  let analyzedChunkImportCss;
  const processImportedCss = (files) => {
    // 20+ lines of processing logic...
  }
  // Another 30+ lines handling imports and more processing...
  return tags;
}
```

Break it down into smaller, focused functions:

```ts
const toStyleSheetLinkTag = (file, toOutputPath) => ({
  tag: 'link',
  attrs: {
    rel: 'stylesheet',
    crossorigin: true,
    href: toOutputPath(file),
  },
});

const getCssFilesForChunk = (chunk, seenChunks = new Set(), seenCss = new Set()) => {
  // Logic to collect CSS files from chunks
}

const getCssTagsForChunk = (chunk, toOutputPath) => 
  getCssFilesForChunk(chunk).map(file => 
    toStyleSheetLinkTag(file, toOutputPath)
  );
```

This approach:
- Makes the code easier to understand and reason about
- Improves testability by isolating specific behaviors
- Allows for better reuse of functionality
- Creates a clearer separation of concerns

When refactoring complex logic, also consider extracting helper functions that handle setup tasks or conditional logic blocks to make the main function flow more obvious.

---

## dependency constraint consistency

<!-- source: python-poetry/poetry | topic: Configurations | language: Toml | updated: 2025-01-09 -->

Maintain consistent formatting and rationale for dependency version constraints in configuration files. Use caret notation (`^1.0.0`) instead of range notation (`>=1,<2`) for cleaner syntax when specifying compatible version ranges. When constraining to specific Python versions, choose between explicit version strings (`"3.7"`) and comparison operators (`"<3.8"`) based on maintainability - use explicit versions when targeting a single version for easier removal later, and comparison operators for broader compatibility ranges.

For critical dependencies, document the reasoning behind constraint choices. Exact pinning should be intentional and documented (e.g., "We pin poetry-core exactly since Poetry 1.3 because we release Poetry for every poetry-core bugfix"). Avoid yanked versions by checking package status before updating constraints.

Example:
```toml
# Preferred: caret notation for compatible ranges
requests-toolbelt = "^1.0.0"

# Avoid: range notation
requests-toolbelt = ">=1,<2"

# Explicit version for single-version targeting (easier to grep/remove)
"backports.cached-property" = { version = "^1.0.2", python = "3.7" }

# Comparison for broader compatibility
importlib-metadata = { version = "^4.4", python = "<3.10" }
```

This ensures configuration files are maintainable, constraints are intentional, and version specifications follow consistent patterns across the project.

---

## Framework-specific entrypoints organization

<!-- source: vercel/turborepo | topic: Next | language: Other | updated: 2025-01-06 -->

When creating libraries that integrate with Next.js or other frameworks, organize your code with separate entrypoints for each supported framework. This approach improves bundling efficiency, prevents dependency conflicts, and makes framework-specific code easier to maintain.

Structure your exports with clear path separation:
- Use a base path for framework-agnostic components
- Use framework-specific paths for specialized integrations

For example:

```js
// In your package.json exports
{
  "exports": {
    "./link": "./dist/link.js",         // Basic HTML component
    "./next-js/link": "./dist/next-link.js",  // Next.js specific implementation
    "./svelte/link": "./dist/svelte-link.js"  // Svelte specific implementation
  },
  "peerDependencies": {
    "next": ">=15"  // Specify version ranges when possible
  }
}
```

In your framework-specific implementation:

```tsx
// ./packages/ui/src/next-link.tsx
import Link from 'next/link';
import type { ComponentProps } from 'react';

type CustomLinkProps = ComponentProps<typeof Link>;

export function CustomLink({ children, ...props }: CustomLinkProps) {
  return (
    <Link className="text-underline hover:text-green-400" {...props}>
      {children}
    </Link>
  );
}
```

This pattern allows consumers to import exactly what they need while bundlers can properly tree-shake unused framework code. It also enhances type safety since framework-specific props and behaviors are isolated to their respective entrypoints.

---

## Follow metadata specifications

<!-- source: alacritty/alacritty | topic: Documentation | language: Xml | updated: 2025-01-03 -->

When writing metadata files (such as AppStream, package manifests, or configuration files), always consult and follow the official specifications precisely. Pay special attention to case-sensitive identifiers, valid values, and required formats.

Key practices:
- Verify case-sensitivity requirements for identifiers (e.g., "Apache-2.0" not "APACHE-2.0" for SPDX license IDs)
- Check that values are from approved lists (e.g., only specific licenses are valid for AppStream metadata_license)
- Use validators to ensure compliance before submission
- Include both modern and legacy tags when maintaining backward compatibility
- Reference official documentation sources in comments when standards are unclear

Example from AppStream metadata:
```xml
<!-- Correct: Case-sensitive SPDX license ID -->
<project_license>Apache-2.0</project_license>
<!-- Valid metadata license from approved list -->
<metadata_license>MIT</metadata_license>

<!-- Modern tag with legacy compatibility -->
<developer_name>Developer Name</developer_name>
<developer id="org.example">
  <name>Developer Name</name>
</developer>
```

This prevents validation failures, ensures compatibility across different parsers, and maintains professional documentation standards.

---

## Avoid unintentional defaults

<!-- source: hyprwm/Hyprland | topic: Configurations | language: Yaml | updated: 2025-01-03 -->

When designing configuration interfaces, be intentional about default values and consider their impact on user behavior and data quality. Avoid defaults that users might unconsciously accept without proper consideration, especially for critical settings.

For form configurations, consider forcing explicit user choices rather than providing convenient defaults that might be ignored. Users often have "attention problems and just ignore" default selections, leading to poor data quality where values are not "hand picked and relevant."

Example approaches:
- Use `multiple: true` in dropdowns to prevent default selection and force explicit choice
- Clearly communicate when configuration values are required vs optional, as changing these requirements can have broader system implications
- Consider the downstream impact of configuration changes before relaxing or tightening requirements

This principle helps ensure that configuration values reflect deliberate user decisions rather than oversight or convenience.

---

## Explain documentation rationale

<!-- source: hyprwm/Hyprland | topic: Documentation | language: Yaml | updated: 2025-01-02 -->

When writing user-facing documentation, always explain WHY a guideline or requirement exists, not just WHAT users should do. Users are more likely to follow instructions when they understand the reasoning behind them.

Avoid "trust me bro" documentation that simply states rules without context. Instead, provide clear explanations of the problems that guidelines solve or the benefits they provide.

Example from issue templates:
```yaml
# Poor - just states the rule
description: Please attach log files instead of pasting them.

# Better - explains the reasoning  
description: When including text files (such as logs or config), please **always ATTACH** them, and not paste them directly. This is important because pasting text directly clutters the issue with unnecessary keywords, making github issue search useless.
```

This approach helps users understand the impact of their actions and leads to better compliance with documentation guidelines.

---

## config hygiene

<!-- source: wavetermdev/waveterm | topic: Configurations | language: Json | updated: 2024-12-26 -->

Keep repository configuration files canonical, documented, and free of personal workspace/debug artifacts.

Why: Config files determine runtime behavior and developer onboarding. Committing personal IDE or temporary debug configs pollutes the repo, causes accidental formatting/behavior differences, and hides the canonical way to run the app. Likewise, config schemas consumed by the app should be explicit and stable so tooling/parsers and CI can validate them.

How to apply:
- Do not commit personal workspace or IDE/debug files (e.g., .vscode/launch.json). Add them to .gitignore, or commit a vetted template (e.g., .vscode/launch.json.template) with instructions.
  - Example: remove .vscode/launch.json and document the standard run command: `task electron:dev`.
- Provide and document one canonical method to run services in dev (tasks, npm scripts, Makefile entry). Put those instructions in CONTRIBUTING.md or README_DEV.md so everyone uses the same flow.
- Make config formats explicit and machine-friendly. Add clear fields rather than relying on ad-hoc parsing, and document accepted separators/formatting.
  - Example (from keybindings):
    {
      "command": "app:openConnectionsView",
      "keys": [],
      "commandStr": "/mainview connections"
    }
  Document parsing rules (e.g., comma, whitespace, or '\n' accepted as separators) and enforce via a linter or schema validator in CI.
- If developers need personal debugging conveniences, keep them local (ignored) or provide documented templates and scripts to reproduce behavior without committing per-user files.

Enforcement suggestions:
- Add lints/CI checks that validate config schemas and fail on unexpected workspace/debug files being committed.
- Maintain a small set of canonical templates and clear developer docs for running and debugging the app.

References: discussion indices [0, 1].

---

## avoid unnecessary operations

<!-- source: alacritty/alacritty | topic: Performance Optimization | language: Rust | updated: 2024-12-22 -->

Eliminate redundant work by implementing early returns, avoiding unnecessary clones/references, and skipping computations when results won't be used. This fundamental optimization reduces CPU cycles and improves performance across hot code paths.

Key strategies:
- Use early returns to exit functions when conditions make further processing unnecessary
- Pass values by move instead of creating unnecessary references that require clones
- Check cheaper conditions first and return early when expensive operations can be skipped
- Avoid rendering or computing values that won't be visible or used

Example from the codebase:
```rust
// Before: Unnecessary reference and potential clone
match (&event.payload, event.window_id.as_ref()) {

// After: Direct value usage, avoiding clone
match (event.payload, event.window_id.as_ref()) {

// Early return optimization
if self.frame().damage_all || selection == self.old_selection {
    return; // Skip expensive selection damage computation
}
```

This approach is particularly effective in rendering pipelines, event processing loops, and frequently called functions where small optimizations compound significantly.

---

## Synchronize resource claims

<!-- source: wavetermdev/waveterm | topic: Concurrency | language: TypeScript | updated: 2024-12-20 -->

When asynchronous operations cross process or component boundaries (backend <> frontend, websocket events, UI lifecycle), design explicit synchronization instead of relying on ad-hoc timing. Apply these rules:

- Prefer authoritative coordination: move critical claim/transfer logic to the authoritative service (backend). Operations that modify ownership (delete workspace, transfer window ownership) should be atomic and return an explicit result the client can act on (e.g., replacementId or empty). The client should only perform follow-up actions after receiving that result.

  Example (pseudo):
  // server: atomically choose replacement or clear owner and return id or empty string
  func DeleteWorkspace(id) -> string {
    if findReplacementForWindow(ownerWindow) {
      claimReplacement(replacementId, ownerWindow)
      return replacementId
    }
    cleanupWindowOwner(ownerWindow)
    return ""
  }

  // client: act only on server response
  const replacement = await WorkspaceService.DeleteWorkspace(workspaceId)
  if (replacement) {
    await switchWorkspace(replacement)
  } else {
    window.destroy()
  }

- If some coordination must remain client-side, use explicit coordination primitives not blind delays: prefer promises/events/component-ready hooks over setTimeout. Only use timeouts as a fallback when no readiness signal exists.

  Example (UI focus):
  // prefer event-driven readiness
  await sessionView.ready()
  inputModel.giveFocus()

  // fallback only if necessary
  setTimeout(() => inputModel.giveFocus(), 50)

- For out-of-order or eventual-consistency events (e.g., websocket update before add), implement bounded retries with short delay/backoff and a clear failure path. Log retries and abort after N attempts to avoid infinite loops.

  Example (retry for missing line):
  async function ensureLineAndApply(lineId, update) {
    for (let attempt=0; attempt<5; attempt++) {
      if (lines[lineId]) { lines[lineId].apply(update); return }
      await sleep(100 * (attempt+1)) // small backoff
    }
    console.warn(`Failed to find line ${lineId} after retries`)
  }

- General rules: use compare-and-swap or explicit claim APIs when possible; bound retries and timeouts; make failure modes observable (logs/metrics); write tests for race scenarios.

Motivation: these practices prevent races between concurrent actors, make system behavior deterministic, and move complex invariants into the authoritative layer where they can be enforced reliably. References: discussions on workspace deletion/claim races (0), UI focus timing (1), and websocket update ordering with retry (2).

---

## Avoid chatty mouse events

<!-- source: wavetermdev/waveterm | topic: Performance Optimization | language: TSX | updated: 2024-12-19 -->

Motivation: High-frequency events like mousemove are "chatty" and can cause excessive CPU usage and layout thrashing. Prefer lower-rate pointer events (mouseenter/mouseleave) or throttled handlers attached to specific elements, and minimize repeated DOM writes by toggling classes. Always attach and remove listeners in lifecycle hooks and guard against null refs to avoid leaks.

How to apply:
- Replace document-level or continuous mousemove handlers with a lightweight hover hotspot (e.g., a full-width fixed div) that uses mouseenter to reveal UI and mouseleave on the revealed element to hide it.
- Toggle CSS classes rather than repeatedly writing inline styles to reduce layout and paint costs.
- Use useEffect (or equivalent) to add/remove event listeners and to read element sizes once, guarding ref nulls.
- If you must track movement, throttle/debounce the handler and limit work done per call.

Example (pattern adapted from the discussion):

// setup
const autoHideTabBar = settings?.["window:autohidetabbar"] ?? false;

useEffect(() => {
  const tabBar = tabbarWrapperRef.current;
  if (!tabBar) return;

  if (!autoHideTabBar) {
    tabBar.style.top = '0px';
    return;
  }

  const tabBarHeight = tabBar.clientHeight + 1;
  tabBar.style.top = `-${tabBarHeight - 10}px`;

  const onEnter = () => {
    // show via class toggle to avoid many inline writes
    tabBar.classList.add('tab-bar-wrapper-auto-hide-visible');
    tabBar.style.top = '0px';
    tabBar.addEventListener('mouseleave', onLeave);
  };

  const onLeave = () => {
    tabBar.classList.remove('tab-bar-wrapper-auto-hide-visible');
    tabBar.style.top = `-${tabBarHeight - 10}px`;
    tabBar.removeEventListener('mouseleave', onLeave);
  };

  // attach to the hotspot element (not document) to avoid global mouse tracking
  tabbarWrapperRef.current.addEventListener('mouseenter', onEnter);
  return () => {
    tabbarWrapperRef.current?.removeEventListener('mouseenter', onEnter);
    tabbarWrapperRef.current?.removeEventListener('mouseleave', onLeave);
  };
}, [autoHideTabBar]);

Notes:
- Guard ref accesses (tabbarWrapperRef.current) to prevent runtime errors.
- Prefer class toggles for visibility so CSS handles transitions and reduces JS-driven layout changes.
- If you need finer-grained movement tracking, apply throttling and keep DOM reads/writes batched.

---

## Descriptive, unambiguous identifiers

<!-- source: vercel/turborepo | topic: Naming Conventions | language: Rust | updated: 2024-12-17 -->

Choose names that clearly express intent and behavior while avoiding ambiguity. Identifiers should communicate their purpose to other developers without requiring them to read implementation details.

When naming functions, prefer specific, action-oriented names over vague descriptions:
```rust
// Avoid: Not clear what "update" means in this context
fn update_task_selection_pinned_state(&mut self) -> Result<(), Error> {
    self.preferences.set_active_task(None)?;
    Ok(())
}

// Better: Clearly communicates the function's purpose
fn clear_pinned_task(&mut self) -> Result<(), Error> {
    self.preferences.set_active_task(None)?;
    Ok(())
}
```

Consider context when choosing names. If changing visibility (e.g., private to public), ensure the name makes sense in its new context:
```rust
// Private function with implementation-specific name
fn config_init(...) { ... }

// Better name when made public
pub fn create_config(...) { ... }
```

For enum variants and type names, choose terms that accurately reflect their purpose:
- Use `PackagePresenceReason` instead of `PackageChangeReason` when describing why a package is included
- Prefer `direct_dependencies()` over `immediate_dependencies()` to clearly relate to other dependency types
- Choose `LogicalProperty` over the generic `AdditionalProperty`
- Avoid potentially misleading terms like `GlobalFileChanged` when `NonPackageFileChanged` is more precise

When multiple related types exist, names should help clarify their relationships and distinctions.

---

## Warn against sudo

<!-- source: zed-industries/zed | topic: Security | language: Shell | updated: 2024-12-17 -->

Applications that may need elevated privileges should explicitly warn against running the entire application with sudo. Instead, implement and document proper privilege escalation mechanisms (like polkit on Linux) for specific tasks requiring higher permissions.

When your application includes functionality that might tempt users to run it with sudo, provide clear warnings about the security and data integrity risks. Include these warnings in both documentation and relevant UI/CLI interactions.

Example:
```bash
if [[ $EUID -eq 0 ]]; then
    echo "WARNING: Do NOT run this application directly with sudo."
    echo "Doing so may compromise security and make application data unusable."
    echo "See https://example.com/docs/security for proper privilege management."
    exit 1
fi

# For specific elevated tasks, use a dedicated privilege management solution:
setup_elevated_access() {
    if ! command -v pkexec >/dev/null 2>&1; then
        echo "Note: 'pkexec' not detected. You won't be able to edit system files."
        echo "See https://example.com/docs/privileges for more information."
    fi
}
```

This approach isolates privileged operations to specific functions rather than running the entire application with elevated privileges, reducing the security attack surface and preventing potential data corruption.

---

## Favor reusable helpers

<!-- source: wavetermdev/waveterm | topic: Code Style | language: TSX | updated: 2024-12-16 -->

Centralize repeated UI logic and prefer modern, consistent JS style. When you see duplicated logic, ad-hoc class strings, local copies of global state, or repeated boolean checks, extract them into small, well-named helpers (or model/computed methods) and apply consistent ES/React idioms.

Why: centralization improves readability, reduces bugs from divergence, and makes code easier to test and reuse. Using modern patterns (const, for-of, classname helpers) keeps code concise and consistent.

Actionable checklist:
- Use a class-name helper (cn/clsx) to compose classes and avoid manual string concatenation:
  // from discussion
  // bad: className={`tab-bar-wrapper${autoHideTabsBar ? '-auto-hide' : ''}`}
  // better:
  className={cn('tab-bar-wrapper', { 'tab-bar-wrapper-auto-hide': autoHideTabsBar })}
  // and avoid unnecessary fallbacks:
  className={cn('wave-dropdown', className)}

- Extract repeated UI/focus/keybinding logic into model methods or computed helpers so callers just ask the model for intent:
  // suggested pattern
  // inputModel.ts
  isAuxViewFocused(auxView: InputAuxViewType) {
    return GlobalModel.inputModel.hasFocus() ||
           (GlobalModel.getActiveScreen().getFocusType() === 'input' &&
            GlobalModel.activeMainView.get() === 'session' &&
            GlobalModel.inputModel.getActiveAuxView() === auxView);
  }

  // consumer
  const isHistoryFocused = GlobalModel.inputModel.isAuxViewFocused(InputAuxView_History);

- Prefer modern, immutable declarations and iteration:
  - Use const for variables that are not reassigned (e.g., `const tab = ...`, `const elem = this.iconRef.current`).
  - Prefer `for (const item of array)` or array helpers over C-style loops.

- Don’t merge arrays when handling logic differs. Either iterate separately or normalize behavior first; merging is fine only when the processing is identical.

- Keep local component state minimal. If global/shared state already tracks a value (focus, mode, etc.), reuse it instead of duplicating.

Examples from discussions:
- Class composition: className={cn('wave-dropdown', className)} (no `|| ''`)
- Focus logic: move to inputModel.isAuxViewFocused(auxView)
- Iteration/style: use `for (const tab of this.options)` and `const` instead of `let` and C-style loops

Apply this rule in reviews: if you see repeated logic, ad-hoc string building, or duplicated state, request extraction to a helper or model and enforce `const`/`for-of`/cn usage for consistency.

---

## Config accuracy and safety

<!-- source: wavetermdev/waveterm | topic: Configurations | language: Other | updated: 2024-12-16 -->

Confirm that configuration artifacts (docs, config files, and ignore lists) match actual runtime behavior and preserve developer workflows.

Why: Incorrect docs or overly broad ignore rules cause confusion and break common development scenarios (hot UI changes, devcontainer editor settings, in-container git commits).

How to apply:
- Docs: Verify whether a setting requires an app restart by checking the implementation (frontend vs backend) before documenting. Prefer precise, actionable descriptions. Example correction:
| window:autohidetabbar               | bool     | show and hide the tab bar automatically when the mouse moves near the top of the window

- Ignore files: Don’t broadly exclude files that are needed for developer tooling inside devcontainers (e.g., .vscode, .git, .github). If you must ignore something for image size or build reasons, use targeted patterns or explicit negations and document the reason. Examples:
# keep editor & git metadata for devcontainer workflows
!.vscode
!.git

# still ignore node_modules in image builds
node_modules

- Documentation: When an ignore rule deviates from normal expectations (e.g., removing .git or editor settings), add an inline comment or README note explaining why and how to work around it.

Checklist before committing changes to configs:
- Confirm the runtime effect (restart required?) against the implementation (frontend/backend).
- Run a quick devcontainer test: can you open workspace settings and commit from inside the container?
- If ignoring files, prefer minimal, documented exclusions or maintain separate ignore files for container builds vs repository workflows.

Adopting this rule reduces surprises for developers and ensures configuration changes are both accurate and safe for everyday workflows.

---

## Guard nullable values

<!-- source: likec4/likec4 | topic: Null Handling | language: TSX | updated: 2024-12-13 -->

Always check for null/undefined before accessing values or rendering UI instead of relying on non‑null assertions or unconditional usage. Prefer optional chaining and explicit guards in logic and conditional rendering in JSX.

Why: Non-null assertions (`!`) and unconditional rendering can cause runtime exceptions when data is absent. Explicit checks make intent clear and avoid crashes.

How to apply:
- Replace `!` assertions with optional chaining and guards:
  - Bad: let relationId = only(edge.data.relations)!.id;
  - Good: let relationId = only(edge.data.relations)?.id;
           if (relationId) { /* use relationId */ }

- Conditionally render components only when required data exists:
  - Bad: <LikeC4CustomColors customColors={view.customColorDefinitions} />
  - Good: {view.customColorDefinitions && (
      <LikeC4CustomColors customColors={view.customColorDefinitions} />
    )}

Notes:
- Use optional chaining (?.) when a property may be undefined; follow with an if-check if you need to act on the value.
- For JSX, prefer conditional rendering or early returns to avoid passing undefined props or rendering components that expect data.
- Reserve `!` only when you can guarantee the value (and document why). When in doubt, guard.

---

## Propagate errors with context

<!-- source: vitejs/vite | topic: Error Handling | language: TypeScript | updated: 2024-12-12 -->

Always propagate errors with proper context and recovery strategy. Use try-catch blocks for both synchronous and asynchronous operations, ensure error information is preserved, and provide meaningful error messages.

Key practices:
1. Use try-catch over existence checks
2. Preserve error context in async chains
3. Include source information and frames
4. Implement recovery strategies where appropriate

Example:
```typescript
// Instead of:
if (fs.existsSync(srcFile)) {
  const stats = fs.statSync(srcFile)
}

// Do:
try {
  const stats = fs.statSync(srcFile)
} catch (e) {
  if (e.code === 'ENOENT') {
    // Handle missing file case
  }
  // Preserve context and rethrow
  throw new Error(`Failed to read ${srcFile}: ${e.message}`, { cause: e })
}

// For async handlers:
async function middleware(req, res, next) {
  try {
    await processRequest(req)
  } catch (e) {
    // Add context and pass to error handler
    e.url = req.url
    e.frame = generateCodeFrame(e.pos)
    return next(e)
  }
}
```

---

## consistent platform identifiers

<!-- source: electron/electron | topic: Naming Conventions | language: Yaml | updated: 2024-12-10 -->

When naming platform identifiers, choose one naming convention and use it consistently throughout the codebase. Prefer established ecosystem standards when available, such as Node.js `process.platform` values (`win32`, `darwin`, `linux`) over custom variations.

Avoid mixing different names for the same platform concept (e.g., `windows`, `win`, `win32` all referring to Windows). This creates confusion and requires unnecessary translation logic.

Example of the problem:
```yaml
# Inconsistent - multiple names for Windows platform
artifact-platform: 'windows'  # in one place
build-key: 'win32'            # in another place  
target: 'win'                 # in yet another place
```

Example of the solution:
```yaml
# Consistent - using Node.js process.platform convention
artifact-platform: 'win32'   # everywhere
build-key: 'win32'           
target: 'win32'              
```

This eliminates the need for conditional transformations like `inputs.artifact-platform == 'windows' && 'win32' || inputs.artifact-platform` and makes the codebase more predictable and maintainable.

---

## consistent semantic naming

<!-- source: python-poetry/poetry | topic: Naming Conventions | language: Yaml | updated: 2024-12-08 -->

Names should follow established team conventions while accurately reflecting their purpose and functionality. Inconsistent naming schemes and misleading identifiers create confusion and maintenance overhead.

When naming identifiers, ensure they:
1. Adhere to established team naming patterns (e.g., use slashes instead of spaces in labels)
2. Accurately describe what the identifier represents or does

Examples:
- Instead of `test poetry export` (violates naming scheme), use `test/export`
- Instead of `poetry-update` (misleading - doesn't actually update), use `poetry-sync` (accurately reflects synchronization behavior)

This applies to all identifiers including variables, functions, classes, configuration keys, labels, and hook names. Consistent and accurate naming improves code readability and reduces cognitive load for team members.

---

## Pin tool versions explicitly

<!-- source: python-poetry/poetry | topic: CI/CD | language: Yaml | updated: 2024-11-30 -->

Always specify exact versions for tools and dependencies in CI/CD workflows to ensure reproducible builds and avoid issues with cached or default system versions. Use package managers and version pinning rather than relying on system-installed tools.

When possible, prefer managed binaries over system defaults. For example, use npm-managed tools via npx, and pin Python versions to specific releases rather than using generic version specifiers.

Example:
```yaml
# Instead of:
- run: hugo --minify --logLevel info
python-version: ["3.6", "3.7", "3.8", "3.9", "pypy-3.7"]

# Use:
- run: npx hugo --minify --logLevel info  
python-version: ["3.6", "3.7", "3.8", "3.9", "pypy-3.7-v7.3.7"]
```

This practice prevents build failures caused by version mismatches, ensures consistent behavior across different runner environments, and takes advantage of bug fixes in newer tool versions.

---

## Precise documentation language

<!-- source: vitejs/vite | topic: Documentation | language: Other | updated: 2024-11-27 -->

Use specific and clear language in all documentation to improve user understanding and avoid ambiguity. Favor precise terminology over vague descriptors, while balancing specificity with maintainability concerns.

Examples:
- Instead of referring to "the old version," specify the exact version number: "Vite 5 (old version)"
- Use semantically appropriate HTML elements in documentation (e.g., `<strong>` instead of `<b>`)
- When describing scope or applicability (like in license files or feature documentation), ensure language precisely defines the boundaries

```html
<!-- Instead of this -->
<p>
  This documentation describes <b>the old</b> Vite version. For the latest
  version, see <a href="https://vite.dev/">the latest document</a>.
</p>

<!-- Use this -->
<p>
  This documentation covers Vite 5 <strong>(old version)</strong>. For the latest
  version, see <a href="https://vite.dev">https://vite.dev</a>.
</p>
```

Consider the maintenance implications when determining how specific to be. Sometimes very precise details (like future version numbers) might create maintenance burden that outweighs the benefit of specificity.

---

## Permission hierarchy awareness

<!-- source: vitejs/vite | topic: Security | language: Yaml | updated: 2024-11-26 -->

When implementing permission checks, understand the hierarchical nature of permissions and avoid redundant checks. Higher-level permissions typically include lower-level ones. Ensure your authorization logic accounts for permission relationships to maintain security while keeping code efficient.

Example:
```javascript
// Inefficient - checks each permission separately
const hasAccess = data.user.permissions.triage || 
                 data.user.permissions.write || 
                 data.user.permissions.admin;

// Better - understands permission hierarchy
const hasAccess = ['triage', 'write', 'admin'].some(p => data.user.permissions[p]);

// Most efficient - if you know the hierarchy (write and admin include triage)
const hasAccess = data.user.permissions.triage || 
                 data.user.permissions.write || 
                 data.user.permissions.admin;
```

The most appropriate implementation depends on the system's permission model and whether permission hierarchies are guaranteed to remain consistent over time.

---

## Keep documentation together

<!-- source: alacritty/alacritty | topic: Documentation | language: Other | updated: 2024-11-23 -->

Documentation should keep related information physically close together rather than separating it across different sections. When documenting configuration options, provide detailed explanations and defaults directly with each option definition instead of collecting them in distant sections.

Users should not have to scroll through large portions of documentation to find complete information about a single field. Each documented item should be self-contained with its description, possible values, platform restrictions, defaults, and examples all in proximity.

For example, instead of:
```
*level* = _"Normal"_ | _"AlwaysOnTop"_
    Sets the window level (Normal, AlwaysOnTop).
    Default: _"Normal"_
```

Provide detailed explanations:
```
*level* = _"Normal"_ | _"AlwaysOnTop"_
    Sets the window level.
    
    *Normal*
        Standard window behavior
    *AlwaysOnTop* 
        Window stays above other windows
        
    Default: _"Normal"_
```

This approach improves documentation usability by ensuring users can find complete information about any feature without extensive navigation, making the documentation more practical and user-friendly.

---

## Prefer flags over conditionals

<!-- source: Homebrew/brew | topic: Configurations | language: Other | updated: 2024-11-23 -->

When implementing environment-specific or version-dependent behavior, use feature flags or configuration variables instead of complex conditional logic. This approach makes configuration management more maintainable and easier to adjust when requirements change.

For example, instead of nested conditionals to handle OS version-specific behavior:

```bash
# Before: Complex conditional logic
if [[ "$OS_VERSION" -ge 10.13 && "$OS_VERSION" -lt 14 ]]; then
  # Version-specific behavior
  if [[ condition_check ]]; then
    # Do something
  fi
fi

# After: Using a configuration flag
# In initialization code:
if [[ "$OS_VERSION" -ge 10.13 && "$OS_VERSION" -lt 14 ]]; then
  append_to_cccfg "h"  # Add a feature flag
fi

# In implementation code:
if [[ "${HOMEBREW_CCCFG}" = *h* ]]; then
  # Do version-specific behavior
fi
```

This pattern:
1. Centralizes version checks and keeps implementation clean
2. Makes it obvious when the configuration can be removed
3. Prevents configuration code from running in unsupported environments
4. Creates an explicit interface between environment detection and feature behavior

---

## Use design tokens

<!-- source: wavetermdev/waveterm | topic: Code Style | language: Other | updated: 2024-11-22 -->

Centralize visual styles and prefer theme variables over hardcoded values. Motivation: duplicate hardcoded colors, repeated color classes, inconsistent sizing, and ad-hoc styles reduce maintainability and make global theme changes error-prone. How to apply it:

- Colors: never hardcode component colors. Use theme variables (design tokens) declared in the global stylesheet (app.less/app.scss). Move color utility classes into the central file and reference them from components. Example central rule:
  /* app.less */
  .icon.color-green i { color: var(--color-green); }
  .icon.color-default i { color: var(--color-default); }

  Then in component styles, avoid duplicating color classes and instead ensure rendered icons include the shared "icon" class (e.g., add the "icon" class in renderIcon output).

- Fonts: use the standardized font variable shorthand. Example:
  /* use the shorthand to get family, size, weight */
  .markdown { font: var(--base-font); }

- Sizing: follow approved size increments for UI fonts/icons (e.g., 12.5px and 15px where the typeface is optimized in 2.5px steps). Match icon font-size to other SVG icons by using the shared icon class rather than per-component overrides.

- File format & maintainability: prefer SCSS for new/complex component styles to leverage nesting and variables. If converting a file, migrate to .scss and import shared variables rather than duplicating them locally.

Checklist for PRs:
- Are colors using theme variables (no raw rgba/#hex in component files)?
- Are color/icon utility rules declared in the central stylesheet? Are icons rendered with the shared "icon" class?
- Is the font set via var(--base-font) where applicable?
- Are sizes following approved increments and consistent with siblings?
- For larger styles, was the file migrated to SCSS and shared tokens imported?

Following this rule keeps styles consistent, reduces duplication, and makes global theme changes low-risk.

---

## Platform-specific configuration separation

<!-- source: zen-browser/desktop | topic: Configurations | language: Other | updated: 2024-11-22 -->

Configuration options should be separated between common/shared settings and platform-specific settings to avoid build failures and ensure proper cross-platform compatibility. When a configuration option is not supported on all target platforms or architectures, it must be moved from common configuration files to individual platform-specific configuration files.

This separation prevents build failures that occur when unsupported options are included in common configurations. For example, DRM/Widevine support varies by architecture - Linux aarch64 doesn't support it while other platforms do.

Example of proper separation:
```
# configs/common/mozconfig - Remove platform-specific options
# ac_add_options --enable-eme=widevine  # REMOVED - not supported on all platforms

# configs/linux/mozconfig - Add for supported architectures only
if test "$ARCH" != "aarch64"; then
    ac_add_options --enable-eme=widevine
fi

# configs/macos/mozconfig - Add for supported platforms
ac_add_options --enable-eme=widevine
```

Before adding any configuration option to a common/shared configuration file, verify that it's supported across all target platforms and architectures. If not, place it in the appropriate platform-specific configuration files with proper conditional checks where needed.

---

## Semantic variable naming

<!-- source: hyprwm/Hyprland | topic: Naming Conventions | language: C++ | updated: 2024-11-21 -->

Variable names should clearly convey their purpose, type, and units to improve code readability and prevent errors. Follow these naming conventions:

**Unit specification**: Include units in variable names when dealing with measurements or time values. Use suffixes like `Us` for microseconds, `Ms` for milliseconds, etc.
```cpp
// Bad
void renderData(CMonitor* pMonitor, float duration) {
    m_dLastRenderTimes.push_back(duration / 1000.f);
}

// Good  
void renderData(CMonitor* pMonitor, float durationUs) {
    m_dLastRenderTimes.push_back(durationUs / 1000.f);
}
```

**Intuitive naming**: Choose names that clearly express intent and behavior. Prefer descriptive names over abbreviated ones.
```cpp
// Bad
m_pConfig->addConfigValue("binds:pin_fullscreen", Hyprlang::INT{0});

// Good
m_pConfig->addConfigValue("binds:allow_pin_fullscreen", Hyprlang::INT{0});
```

**Pointer prefixes**: Use `p` prefix only for actual pointer variables, not for other types.
```cpp
// Bad
const auto pwindowCurrentFullscreenState = PWINDOW->m_bIsFullscreen;
const auto pwindowCurrentFullscreenMode = PWINDOW->m_pWorkspace->m_efFullscreenMode;

// Good
const auto CURRENTWINDOWFSSTATE = PWINDOW->m_bIsFullscreen;
const auto CURRENTWINDOWFSMODE = PWINDOW->m_pWorkspace->m_efFullscreenMode;
```

**Case conventions**: Use camelCase for variables and function names, CAPS for constants. Avoid snake_case.
```cpp
// Bad
const auto target_portion = (*PGAPSOUT + *PBORDERSIZE) / (VERTANIMS ? PMONITOR->vecSize.y : PMONITOR->vecSize.x);
size_t space_pos = VALUE.find(' ');

// Good
const auto TARGETPORTION = (*PGAPSOUT + *PBORDERSIZE) / (VERTANIMS ? PMONITOR->vecSize.y : PMONITOR->vecSize.x);
size_t spacePos = VALUE.find(' ');
```

These conventions reduce cognitive load, prevent type-related bugs, and make code self-documenting.

---

## Document algorithmic reasoning

<!-- source: bazelbuild/bazel | topic: Algorithms | language: Other | updated: 2024-11-20 -->

When implementing algorithms that involve data transformations, platform-specific behavior, or non-obvious computational choices, always include comments explaining the underlying reasoning and assumptions. This is especially critical for:

- Data format conversions (endianness, serialization)
- Platform or compiler-specific algorithmic variations
- Complex bit manipulations or mathematical transformations
- Performance optimizations that sacrifice readability

The explanation should clarify why the algorithm is necessary, what assumptions it makes about the data or environment, and any relevant technical context that future maintainers might lack.

Example:
```cpp
// JVM class files use big-endian byte order, but x86/ARM systems are little-endian.
// This function converts between the two representations when reading binary data.
template<typename T>
inline static T swapByteOrder(const T& val) {
  int totalBytes = sizeof(val);
  T swapped = (T) 0;
  for (int i = 0; i < totalBytes; ++i) {
    swapped |= (val >> (8*(totalBytes-i-1)) & 0xFF) << (8*i);
  }
  return swapped;
}
```

Without such documentation, algorithmic choices appear arbitrary and create maintenance burdens for developers who lack the original context.

---

## Use semantically clear names

<!-- source: bazelbuild/bazel | topic: Naming Conventions | language: Other | updated: 2024-11-15 -->

Choose names that clearly express their purpose and avoid patterns that can lead to confusion or bugs. Names should be self-documenting and unambiguous in their meaning.

Key principles:
- **Avoid double negatives**: Use positive method names like `IsKnown()` instead of `!IsUnknown()` to prevent logical errors
- **Use unambiguous values**: Start counters from 1 instead of 0 when 0 could mean "unset" (e.g., `attempt_number` starting from 1 vs `retry_attempt` starting from 0)
- **Drop implementation details**: Remove internal suffixes like `_src` from public-facing names
- **Use accurate spelling**: Fix typos like `ASSESMBLER_WITH_C_PREPROCESSOR` → `ASSEMBLER_WITH_C_PREPROCESSOR`
- **Generalize when appropriate**: Rename `_is_versioned_shared_library_extension_valid` to `_is_versioned_library_extension_valid` for broader applicability

Example of avoiding double negatives:
```cpp
// Confusing - double negative can lead to bugs
if (!command_wait_duration_ms.IsUnknown()) {
    // This was actually a bug in the original code
}

// Clear - positive logic is easier to understand
if (command_wait_duration_ms.IsKnown()) {
    // Intent is immediately clear
}
```

Example of unambiguous field naming:
```proto
// Ambiguous - 0 could mean "first attempt" or "field not supported"
int32 retry_attempt = 8;  // starts from 0

// Clear - distinguishes between first attempt vs unsupported field
int32 stream_attempt_number = 8;  // starts from 1
```

---

## Use appropriate logging levels

<!-- source: python-poetry/poetry | topic: Logging | language: Python | updated: 2024-11-15 -->

Use debug-level logging for technical details and error information that aids developer troubleshooting, while keeping user-facing messages clean and informative. Avoid exposing verbose technical details directly to users, but ensure they are available for debugging.

Technical error details, exception information, and diagnostic data should be logged at debug level to help developers troubleshoot issues without overwhelming end users. User-facing messages should remain concise and actionable.

Example:
```python
try:
    SystemGit.clone(url, target)
except CalledProcessError as e:
    logger.debug("Git command returned the following error:\n%s", e.stderr)
    raise PoetryConsoleError(
        f"Failed to clone {url}, check your git configuration and permissions"
        " for this repository."
    )
```

Also add debug logging for edge cases and error conditions that might not be immediately obvious:
```python
def get_highest_priority_hash_type(hash_types: set[str]) -> str | None:
    if not hash_types:
        return None
    
    for prioritised_hash_type in prioritised_hash_types:
        if prioritised_hash_type in hash_types:
            return prioritised_hash_type
    
    logger.debug('None of the hash types %s is in prioritized_hash_types', hash_types)
    # ... handle fallback cases
```

---

## optimize algorithmic efficiency

<!-- source: python-poetry/poetry | topic: Algorithms | language: Python | updated: 2024-11-11 -->

Choose efficient algorithms and data structures to avoid unnecessary computational complexity. Look for opportunities to replace expensive operations with more efficient alternatives, especially when dealing with collections and search operations.

Key optimization patterns to apply:

1. **Avoid O(n) operations when O(1) alternatives exist**: Replace `list.pop()` with set-based approaches, use appropriate data structures for the task
2. **Use specialized search methods**: Prefer `iter_prefix()` over full iteration when searching by prefix
3. **Apply short-circuit evaluation**: Order boolean conditions to avoid expensive operations in common cases
4. **Choose appropriate collection types**: Use `set()` for deduplication instead of manually checking lists, use generators/iterables instead of materializing full lists when possible

Example of inefficient vs efficient approach:
```python
# Inefficient: O(n) list.pop operation
for i, dep in enumerate(dependencies):
    if dep.constraint.is_empty():
        new_dependencies.append(dependencies.pop(i))

# Efficient: O(1) set-based blacklist approach  
blacklist = set()
for dep in dependencies:
    if dep.constraint.is_empty():
        blacklist.add(dep)
        break

# Later: skip blacklisted items
for dep in dependencies:
    if dep not in blacklist:  # O(1) lookup
        process(dep)
```

Always consider the computational complexity of your chosen approach and whether a more efficient algorithm or data structure could achieve the same result.

---

## Self-referential worker URLs

<!-- source: vitejs/vite | topic: Networking | language: JavaScript | updated: 2024-11-11 -->

When creating Web Workers for network communication, use self-referential URL patterns that are resilient to file renaming. This improves portability and reliability of your networking code.

For optimal worker initialization, consider these approaches:
- Use the direct self-reference: `new Worker(import.meta.url)`
- Or with explicit URL construction: `new Worker(new URL(import.meta.url))`
- Or using location: `new Worker(self.location.href)`

```javascript
// Recommended approach - resilient to file renaming
const worker = new Worker(new URL(import.meta.url));

// Alternative when referencing other worker files
const worker = new Worker(new URL('./worker.js', import.meta.url));
```

Be aware that when using the same script for both main thread and worker (self-referential pattern), bundlers like Vite will need to bundle the script twice, potentially increasing bundle size but allowing for shared code between contexts.

---

## Boundary case handling

<!-- source: vercel/turborepo | topic: Algorithms | language: Rust | updated: 2024-11-08 -->

Always handle boundary conditions explicitly in algorithms to prevent unexpected behavior. When implementing algorithms that involve iteration, traversal, or boundary checks, consider different approaches based on the specific requirements:

1. **For cyclic collections**:
   - Use modulo arithmetic for elegant wraparound behavior:
   ```rust
   // When implementing next/previous functionality
   if num_rows > 0 {
       self.selected_task_index = (self.selected_task_index + 1) % num_rows;
       // Instead of manual clamping which would stop at boundaries
   }
   ```

2. **For underflow prevention**:
   - Consider using checked operations with fallbacks:
   ```rust
   // Alternative to modulo for previous index
   self.selected_task_index = self.selected_task_index.checked_sub(1).unwrap_or(num_rows - 1);
   ```

3. **For tree/graph traversal**:
   - Be explicit about traversal depth (shallow vs deep):
   ```rust
   // When shallow references are needed (not the whole graph)
   let references = all_modules_iter([self.source].into_iter())
   ```
   
   - Implement early termination for efficiency:
   ```rust
   fn visit_stmt(&mut self, stmt: &Stmt) {
       if self.abort {
           return; // Skip further traversal if abort flag is set
       }
       stmt.visit_children_with(self);
   }
   ```

4. **For pattern matching**:
   - Consider all possible matching paths:
   ```rust
   // Instead of hard if/else for pattern matching
   let (matches_pattern, does_not_match) = pattern.split_could_match("./");
   // Handle both possibilities appropriately
   ```

Explicit boundary handling improves code correctness, readability, and helps prevent subtle bugs that appear only in edge cases.

---

## Manage configuration inheritance carefully

<!-- source: vitejs/vite | topic: Configurations | language: TypeScript | updated: 2024-11-07 -->

When designing configuration systems, establish clear default values and inheritance patterns. Follow these principles:

1. Set explicit defaults that can be overridden by frameworks and users
2. Use helper functions for merging configurations that handle arrays and nested objects appropriately
3. Allow framework-level defaults to be overridden by user configurations
4. Document the configuration resolution order

Example:
```js
// Bad - Hard to override defaults
config.isSPA = true;

// Good - Allows framework and user overrides
config.isSPA ??= true;

// Bad - Direct object merge loses array handling
const merged = { ...defaults, ...userConfig };

// Good - Use helper that handles arrays and nested objects
const merged = mergeWithDefaults(defaults, userConfig);

// Good - Framework providing defaults while allowing user override
export function frameworkConfig(userConfig) {
  return mergeConfig({
    build: {
      minify: false
    },
    dev: {
      port: 3000
    }
  }, userConfig);
}
```

This approach ensures configuration values are predictable, maintainable, and properly documented while providing flexibility for both framework authors and end users.

---

## avoid brittle algorithms

<!-- source: bazelbuild/bazel | topic: Algorithms | language: Python | updated: 2024-11-06 -->

Replace fragile algorithmic approaches with robust, well-tested alternatives. Brittle algorithms that rely on manual parsing, string manipulation, or assumptions about data format are prone to failure and difficult to maintain.

When processing structured data, prefer established parsing techniques over ad-hoc string operations. For example, replace manual token splitting with regex patterns or proper parsers that handle edge cases gracefully.

Example of improvement:
```python
# Brittle approach - manual string splitting
tokens = line.split(maxsplit=2)
label = tokens[0]
if tokens[1][0] != "(" or tokens[1][-1] != ")":
    raise ValueError(f"{tokens[1]} in {line} not surrounded by parentheses")
config_hash = tokens[1][1:-1]

# Robust approach - regex matching
result = CQUERY_RESULT_LINE_REGEX.search(line)
```

Similarly, in complex systems with error propagation, design algorithms that properly store and handle errors at each layer rather than relying on fragile assumptions about error bubbling behavior. This ensures your algorithms remain reliable as the system evolves.

---

## Configuration validation feedback

<!-- source: alacritty/alacritty | topic: Configurations | language: Rust | updated: 2024-10-31 -->

Always validate configuration options and provide clear feedback to users about potential issues. This includes warning about unused configuration keys, preventing redundant options, and ensuring cross-platform compatibility.

Key practices:
1. **Warn about unused keys**: Implement logging for configuration keys that are parsed but not used, helping users identify typos or deprecated settings
2. **Avoid redundant options**: When designing configuration structures, ensure there's no ambiguity between `None` and default enum values - choose one approach consistently
3. **Cross-platform validation**: Use `allow(unused)` instead of `cfg` attributes for configuration fields to prevent warnings on platforms where the feature isn't available
4. **Validate combinations**: Require at least one valid option when multiple configuration fields are mutually dependent

Example implementation:
```rust
// Warn about unused keys during deserialization
for key in unused.keys() {
    log::warn!(target: LOG_TARGET, "Unused config key: {}", key);
}

// Avoid redundant options - choose Option<T> OR T::Default, not both
pub struct WindowConfig {
    // Good: Clear intent
    pub window_level: WindowLevel, // with Default trait
    
    // Avoid: Ambiguous between None and WindowLevel::Normal
    // pub window_level: Option<WindowLevel>,
}

// Validate required combinations
if !content.hyperlinks && content.regex.is_none() {
    return Err("At least one of hyperlink or regex must be specified");
}
```

This approach prevents configuration errors that can be difficult to debug and improves the user experience by providing immediate feedback about configuration issues.

---

## consistent CSS spacing

<!-- source: zen-browser/desktop | topic: Code Style | language: Css | updated: 2024-10-29 -->

Ensure consistent spacing across UI components by using CSS custom properties for padding/margins and applying spacing only when elements exist. This prevents visual inconsistencies between different UI states and modes.

Use CSS custom properties for consistent spacing values:
```css
#TabsToolbar {
  padding: var(--zen-toolbox-padding);
}
```

Apply spacing conditionally using CSS selectors to prevent unnecessary gaps:
```css
/* Only apply margin when pinned tabs exist */
#vertical-pinned-tabs-container:has(tab:not([hidden])) {
  margin-bottom: 8px;
}
```

This approach ensures that spacing remains consistent across different modes while preventing alignment issues when certain elements are not present.

---

## Clarify configuration examples

<!-- source: bazelbuild/bazel | topic: Configurations | language: Markdown | updated: 2024-10-24 -->

Configuration documentation should provide concrete, platform-specific examples rather than generic placeholders, and use precise terminology to avoid confusion. Generic paths like `/path/to/repository` leave developers uncertain about actual implementation.

Replace generic placeholders with realistic examples that show the actual structure and format expected:

```
# Instead of generic:
common --registry="path/to/local/bcr/registry"

# Provide platform-specific examples:
# Windows:
common --registry="file:///C:/Users/johndoe/bazel-central-registry-main"
# Linux:
common --registry="file:////home/johndoe/bazel-central-registry-main"
```

Additionally, ensure configuration instructions are complete by:
- Explaining why certain configurations are needed
- Providing context for workarounds or special cases
- Using precise terminology (e.g., "Bazel modules" vs "Go modules")
- Including references to relevant documentation for complex scenarios

This prevents confusion and reduces back-and-forth questions about implementation details, making configuration setup more straightforward for developers.

---

## Precise documentation links

<!-- source: vercel/turborepo | topic: Security | language: Rust | updated: 2024-10-22 -->

When creating error messages related to security, permissions, or access controls, always provide specific links to relevant documentation. Use query parameters, anchors, or other mechanisms to direct users to the exact section of documentation that addresses their issue, rather than linking to generic pages.

For example, instead of:
```rust
#[error("Insufficient permissions to write to remote cache. Please verify that your role has write access for Remote Cache Artifact at https://vercel.com/docs/accounts/team-members-and-roles/access-roles/team-level-roles")]
```

Prefer:
```rust
#[error("Insufficient permissions to write to remote cache. Please verify that your role has write access for Remote Cache Artifact at https://vercel.com/docs/accounts/team-members-and-roles/access-roles/team-level-roles?resource=Remote+Cache+Artifact")]
```

Specific links reduce friction when users troubleshoot security-related problems and increases the likelihood they'll correctly address permission issues without requiring additional support.

---

## disable sensitive data defaults

<!-- source: zen-browser/desktop | topic: Security | language: JavaScript | updated: 2024-10-20 -->

Features that handle sensitive data such as credit card information, passwords, or personal details should never be enabled by default. These features must require explicit user opt-in to ensure users consciously consent to the handling of their sensitive information.

Enabling sensitive data features by default creates security risks because users may unknowingly have their sensitive information stored, transmitted, or processed without their explicit consent. This violates the principle of informed consent and can lead to data breaches or privacy violations.

Example of problematic code:
```javascript
// BAD: Enabling credit card autofill by default for all countries
pref("extensions.formautofill.creditCards.supported", true);
pref("extensions.formautofill.creditCards.supportedCountries", 'AF,AX,AL,DZ...');
```

Instead, such features should be disabled by default and require user action to enable:
```javascript
// GOOD: Sensitive features disabled by default
pref("extensions.formautofill.creditCards.supported", false);
// Only enable after explicit user consent through settings UI
```

This principle applies to any feature handling sensitive data including payment information, authentication credentials, personal identifiers, or private communications.

---

## Documentation clarity standards

<!-- source: python-poetry/poetry | topic: Documentation | language: Markdown | updated: 2024-10-19 -->

Ensure documentation is grammatically correct, clearly structured, and uses precise terminology. Avoid verbose or repetitive explanations, and provide specific details that help users understand exactly what will happen.

Key practices:
- Use proper grammar and sentence structure ("The '.exe' extension... is placed" should be "The '.exe' extension is added to the file, and it is placed")
- Structure complex information with bullet points or lists for better readability
- Be precise with technical terms (specify "directory path dependencies" rather than just "path dependencies")
- Avoid unnecessarily verbose or repetitive phrasing
- When explaining technical concepts, provide intuitive explanations before detailed technical specifications

Example of improvement:
```
Before: "When set this configuration allows users to configure package distribution format policy for all or specific packages. Specifically, to disallow the use of binary distribution format for all, none or specific packages."

After: "When set, this configuration allows users to disallow the use of binary distribution format for all, none or specific packages."
```

This ensures documentation is accessible, accurate, and actionable for developers at all skill levels.

---

## no braces short ifs

<!-- source: hyprwm/Hyprland | topic: Code Style | language: C++ | updated: 2024-10-12 -->

Remove braces around single-statement if blocks to maintain consistent code style and improve readability. This applies to all control flow statements with single statements, including if, else if, and else blocks.

The codebase follows a consistent style where braces are omitted for single-statement conditionals. This reduces visual clutter and maintains consistency across the project.

**Examples:**

❌ Avoid:
```cpp
if (condition) {
    return;
}

if (pWindow) {
    pWindow->close();
}
```

✅ Prefer:
```cpp
if (condition)
    return;

if (pWindow)
    pWindow->close();
```

**Exception:** Keep braces when the statement spans multiple lines or when it improves clarity in complex nested conditions.

This rule helps maintain visual consistency throughout the codebase and follows the established project conventions. Apply this consistently across all new code and when modifying existing code.

---

## Runtime-agnostic API design

<!-- source: vitejs/vite | topic: API | language: Markdown | updated: 2024-10-11 -->

When designing APIs for systems that support multiple JavaScript runtimes, prioritize decoupling server state from user modules. This approach enables code to run consistently across different environments (Node.js, browsers, edge runtimes) without relying on runtime-specific features.

Instead of directly accessing server state from user modules:

```ts
// Anti-pattern: Tightly coupling server and user code
const vite = createServer()
const { processRoutes } = await vite.ssrLoadModule('internal:routes-processor')
processRoutes(collectRoutes()) // Server state leaks into user module
```

Use virtual modules to mediate between server and user code:

```ts
// Recommended: Decoupled through virtual modules
function vitePlugin() {
  return {
    name: 'virtual-data-provider',
    resolveId(source) {
      return source === 'virtual:app-data' ? '\0' + source : undefined
    },
    async load(id) {
      if (id === '\0virtual:app-data') {
        return `export const data = ${JSON.stringify(serverData)}`
      }
    }
  }
}

// In user module:
import { data } from 'virtual:app-data'
// Process data without direct server dependency
```

For communication between environments, prefer structured APIs with clear transport abstractions rather than relying on shared runtime contexts. If runtime-specific features are needed, isolate them in well-defined interfaces that can be implemented differently across environments.

This pattern enables your code to run in any JavaScript runtime with minimal adaptation, making it suitable for environments like Cloudflare Workers, Deno, browsers, or Node.js servers.

---

## Configure SSR environments

<!-- source: vitejs/vite | topic: Next | language: Markdown | updated: 2024-10-11 -->

When implementing server-side rendering in Next.js projects that use Vite as a bundler, ensure proper environment separation between client and server code. Create distinct module execution environments to prevent leaking server-only code to the client and to support hot module replacement (HMR) during development.

For custom SSR implementations with Next.js and Vite:

```js
// vite.config.js
export default {
  server: { 
    middlewareMode: true 
  },
  environments: {
    // Ensure proper Node.js environment for server components
    node: {
      dev: {
        createEnvironment: createNodeEnvironment,
      },
    },
  },
}

// server.js
const runner = createServerModuleRunner(server.environments.node)

// Use the runner for SSR with HMR support
const { render } = await runner.import('/src/entry-server.js')
```

This configuration helps maintain a clear separation between client and server environments, preventing server-side code from being exposed to the client while enabling HMR support for a smoother development experience with Next.js server components.

---

## Respect provider context

<!-- source: likec4/likec4 | topic: React | language: TSX | updated: 2024-10-09 -->

Ensure library-provided integration points are used so styles and portals behave correctly in host environments (e.g., shadow roots, webcomponents).

Motivation
- Component libraries (Mantine, etc.) expose provider hooks/props for style nonces and portal targets. Using those prevents ad-hoc workarounds and avoids mismatched style injection or portals rendering outside the intended root.

How to apply
1) Use provider APIs for style nonces
- Prefer MantineProvider's getStyleNonce or the useMantineStyleNonce hook instead of manually passing nonce props around. Example pattern:

const root = document.getElementById('root') as HTMLDivElement
const nonce = root.getAttribute('nonce') || undefined

ReactDOM.createRoot(root).render(
  <MantineProvider theme={theme} getStyleNonce={() => nonce} forceColorScheme={scheme}>
    <LikeC4Context>
      <App />
    </LikeC4Context>
  </MantineProvider>
)

Or, if a component needs the nonce at runtime, use the hook inside the component:

function SomeComponent() {
  const styleNonce = useMantineStyleNonce()
  // use styleNonce when necessary
}

2) Forward portal/overlay props when rendering inside shadow roots
- If your component may render inside a shadow root or webcomponent, ensure overlay components (Tooltip, Popover, Modal, etc.) receive portal/target props so portals mount in the same root. Many libraries expose portalProps or accept a target prop. Example:

const ResetControlPointsButton = ({ portalProps }) => {
  return (
    <Tooltip label="Reset all control points" {...portalProps}>
      <Button>Reset</Button>
    </Tooltip>
  )
}

- When using a wrapper or custom button inside a host that provides portalProps, forward them to all overlay/portal-capable children.

Checklist
- Use provider hooks/props (getStyleNonce/useMantineStyleNonce) for style nonce management.
- Configure MantineProvider (or equivalent) at app root so all library components inherit the correct nonce/target.
- Forward portalProps to Tooltip/Popover/Modal/overlays when rendering inside webcomponents or shadow roots.
- Prefer library APIs over custom DOM hacks to keep behavior predictable and secure.

References: 0, 1

---

## validate environment variables

<!-- source: hyprwm/Hyprland | topic: Configurations | language: Shell | updated: 2024-10-08 -->

Always validate that environment variables are properly defined and consistently named before using them in scripts or build processes. Undefined or misnamed variables can cause silent failures or unexpected behavior in builds and deployments.

Check for variable existence and provide meaningful defaults or error messages. Ensure variable names are consistent across different build environments (development, CI, packaging systems like Nix).

Example of problematic code:
```bash
# Bad: Using undefined variable
MESSAGE=$(git show ${GIT_COMMIT_HASH} | head -n 5 | tail -n 1)

# Better: Use defined variable or provide default
HASH=$(git rev-parse HEAD)
MESSAGE=$(git show ${HASH:-HEAD} | head -n 5 | tail -n 1)
```

Consider using build system features like CMake's `add_compile_definitions` instead of shell script environment variable manipulation when possible, as build systems provide better validation and error handling.

---

## Protocol response formatting

<!-- source: microsoft/terminal | topic: Networking | language: C++ | updated: 2024-10-05 -->

When implementing terminal protocol responses (CSI, DCS, OSC sequences), ensure proper formatting with correct terminators and maintain protocol transparency. Terminal protocols require specific response formats with appropriate terminators - CSI responses should use the same C1 mode as the request, DCS responses need proper DCS/ST framing, and OSC responses should echo the same terminator (BEL or ST) as the requesting sequence.

For example, when handling terminal state reports:

```cpp
void AdaptDispatch::_ReturnDcsResponse(const std::wstring_view response) const
{
    const auto dcs = _terminalInput.GetInputMode(TerminalInput::Mode::SendC1) ? L"\x90" : L"\x1BP";
    const auto st = _terminalInput.GetInputMode(TerminalInput::Mode::SendC1) ? L"\x9C" : L"\x1B\\";
    _api.ReturnResponse(fmt::format(FMT_COMPILE(L"{}{}{}"), dcs, response, st));
}
```

Additionally, maintain protocol transparency by avoiding reactions to sequences that should be handled by the terminal client. ConPTY should not react to sequences like "CSI 1 t" or "CSI 2 t" for show/hide operations, as these are the terminal's responsibility. This prevents double-processing and maintains the expected protocol behavior between terminal and application.

---

## Clean network resources

<!-- source: vitejs/vite | topic: Networking | language: TypeScript | updated: 2024-10-03 -->

Always properly close and clean up network connections to prevent memory leaks and resource exhaustion. When establishing WebSocket connections or other network resources, ensure they are explicitly closed and event listeners are removed when no longer needed. Additionally, implement resilient error handling strategies for network operations by using approaches like `Promise.allSettled()` instead of `Promise.all()` to handle partial failures gracefully.

Example:
```javascript
// Bad practice - potential memory leak
async function pingServer(socketProtocol, hostAndPath) {
  const socket = new WebSocket(
    `${socketProtocol}://${hostAndPath}`,
    'vite-ping'
  )
  return new Promise((resolve) => {
    socket.addEventListener('open', () => resolve(true))
    socket.addEventListener('error', () => resolve(false))
  })
}

// Good practice - properly managed resources
async function pingServer(socketProtocol, hostAndPath) {
  const socket = new WebSocket(
    `${socketProtocol}://${hostAndPath}`,
    'vite-ping'
  )
  return new Promise((resolve) => {
    const onOpen = () => {
      cleanup()
      resolve(true)
    }
    const onError = () => {
      cleanup()
      resolve(false)
    }
    
    socket.addEventListener('open', onOpen)
    socket.addEventListener('error', onError)
    
    function cleanup() {
      socket.removeEventListener('open', onOpen)
      socket.removeEventListener('error', onError)
      socket.close()
    }
  })
}

// Use Promise.allSettled for resilient multi-request handling
async function loadResources(urls) {
  // Will continue even if some requests fail
  const results = await Promise.allSettled(
    urls.map(url => fetch(url))
  )
  // Process successful results, handle failures gracefully
  return results.filter(r => r.status === 'fulfilled').map(r => r.value)
}
```

---

## Optimize glob operations

<!-- source: vitejs/vite | topic: Algorithms | language: TypeScript | updated: 2024-10-02 -->

When using glob patterns for file system operations, ensure optimal performance and consistent behavior by configuring glob libraries appropriately and handling paths efficiently:

1. **Specify correct options** for your glob library:
   - Set `expandDirectories: false` when replacing libraries like fast-glob with alternatives that have different defaults
   - Use `absolute: true` when you need absolute paths in results
   - Set appropriate `cwd` to limit search scope and improve performance

```javascript
// Less efficient: may search unnecessary directories
const files = globSync(pattern, {
  ignore: ['**/node_modules/**']
})

// More efficient: properly scoped search with correct options
const files = globSync(pattern, {
  cwd: path.resolve(path.dirname(id), dir),
  absolute: true, 
  expandDirectories: false,
  ignore: ['**/node_modules/**']
})
```

2. **Handle path normalization** consistently by:
   - Normalizing paths before using them in glob patterns
   - Using regex for efficient path extraction when dealing with complex patterns
   - Setting appropriate options for dotfile handling (`dot: true`) when needed

3. **Optimize node_modules handling** in glob patterns:
   - Use regex-based extraction for path segments to avoid unnecessary file traversal
   - Implement path rebasing for patterns that include node_modules to ensure ignore patterns work correctly

Remember that glob operations are computationally expensive, so always consider the algorithmic efficiency of your approach when working with large directory trees.

---

## consistent spacing patterns

<!-- source: prettier/prettier | topic: Code Style | language: Other | updated: 2024-10-01 -->

Maintain consistent spacing patterns around operators, keywords, and interpolation syntax throughout the codebase. This improves readability and reduces cognitive load when scanning code.

Key guidelines:
- Place binary operators at the beginning of new lines in multiline expressions for better visual alignment
- Add spaces after keywords like `new` to distinguish them from method calls: `new (x: number) => void`
- Maintain consistent spacing within interpolation syntax - either `#{$variable}` or `#{ $variable }` but not mixed usage
- Apply the same spacing rules consistently across similar language constructs

Example of good operator placement:
```javascript
const result = someCondition
  && anotherLongCondition
  || fallbackCondition;
```

Example of consistent interpolation spacing:
```scss
// Consistent - no spaces
.icon-#{$size} { }
.text-#{$name} { }

// Consistent - with spaces  
.icon-#{ $size } { }
.text-#{ $name } { }
```

This consistency helps establish clear visual patterns that make code easier to read and maintain, while reducing debates about formatting during code reviews.

---

## Modern configuration formats

<!-- source: prettier/prettier | topic: Configurations | language: Markdown | updated: 2024-09-29 -->

Prefer ES module configuration files with TypeScript annotations over JSON formats for better developer experience and tooling support. Use `.js` or `.mjs` extensions with proper type annotations to enable IDE autocompletion and type safety.

When creating configuration files, especially shared configurations:

1. **Use ES modules instead of JSON**: Choose `prettier.config.js` or `index.js` over `.prettierrc.json` to support dynamic imports and better tooling integration.

2. **Add TypeScript annotations**: Include `/** @type {import("prettier").Config} */` at the top of configuration files to enable IDE autocompletion and type checking.

3. **Set proper package.json fields**: Use `"type": "module"` and `"exports": "./index.js"` for modern module resolution.

4. **Install types as devDependency**: Add `prettier` as a devDependency to support TypeScript annotations.

Example configuration:

```js
/** @type {import("prettier").Config} */
const config = {
  trailingComma: "es5",
  tabWidth: 4,
  singleQuote: true,
};

export default config;
```

Example package.json for shared configs:

```json
{
  "name": "@username/prettier-config",
  "type": "module",
  "exports": "./index.js",
  "devDependencies": {
    "prettier": "^3.3.3"
  }
}
```

This approach provides better IDE support, enables dynamic configuration, and follows modern JavaScript standards while maintaining compatibility with tools like vscode-prettier.

---

## Avoid variable name abbreviations

<!-- source: Homebrew/brew | topic: Naming Conventions | language: Shell | updated: 2024-09-25 -->

Use complete, descriptive variable names instead of abbreviations to enhance code readability and maintainability. Short abbreviations like `dir`, `repo`, and single-letter variables often obscure the purpose of the variable and make code harder to understand for new contributors.

Good:
```bash
normalise_tap_name() {
  local directory="$1"
  local user
  local repository

  user="$(tr '[:upper:]' '[:lower:]' <<<"${directory%%/*}")"
  repository="$(tr '[:upper:]' '[:lower:]' <<<"${directory#*/}")"
  repository="${repository#@(home|linux)brew-}"
  echo "${user}/${repository}"
}
```

Bad:
```bash
normalise_tap_name() {
  local dir="$1"
  local u
  local repo

  u="$(tr '[:upper:]' '[:lower:]' <<<"${dir%%/*}")"
  repo="$(tr '[:upper:]' '[:lower:]' <<<"${dir#*/}")"
  repo="${repo#@(home|linux)brew-}"
  echo "${u}/${repo}"
}
```

Exceptions: Standard abbreviations that are widely understood within the domain or temporary variables with extremely limited scope and obvious context.

---

## Document configuration decisions

<!-- source: Homebrew/brew | topic: Configurations | language: Yaml | updated: 2024-09-24 -->

When making configuration changes, especially those that deviate from standard practices or involve deprecation notices, always include clear explanatory comments. Temporary modifications to configuration settings should document both the reason and expected duration of the exception.

For example, instead of:
```yml
set +o pipefail
DELIMITER="END_LABELS_$(LC_ALL=C tr -dc '[:alnum:]' </dev/urandom | head -c20)"
set -o pipefail
```

Prefer:
```yml
# Temporarily disable pipefail because the random string generation command may fail harmlessly
set +o pipefail
DELIMITER="END_LABELS_$(LC_ALL=C tr -dc '[:alnum:]' </dev/urandom | head -c20)"
set -o pipefail
```

For deprecation notices, clearly specify alternatives:
```yml
# Deprecated: this image will be retired after April 2023
# Use homebrew/ubuntu22.04 or homebrew/ubuntu24.04 instead
echo "The homebrew/ubuntu18.04 image is deprecated and will soon be retired..." > .docker-deprecate
```

When possible, use standardized tools for configuration tasks rather than custom solutions (e.g., `uuidgen` for generating unique identifiers).

---

## Use descriptive names

<!-- source: python-poetry/poetry | topic: Naming Conventions | language: Python | updated: 2024-09-23 -->

Variable, method, and class names should clearly and accurately describe their purpose, content, or behavior. Misleading or vague names create confusion and make code harder to understand and maintain.

Examples of improvements:
- Rename variables to match their actual content: `local_repo` → `lockfile_repo` when it specifically holds lockfile data
- Use action-based names for fixtures: `repo_with_packages` → `repo_add_default_packages` to reflect what it does
- Choose method names that reflect actual behavior: `get_system_python()` → `get_running_python()` when it returns the currently executing Python
- Name parameters clearly: `cached` → `cached_wheel` when specifically referring to wheel caching
- Avoid names that contradict functionality: a `module_name()` function should not do the opposite of converting module names

When reviewing code, ask: "Does this name accurately tell me what this thing is or does?" If there's any ambiguity or if the name could mislead someone reading the code, choose a more descriptive alternative.

---

## maintain API backward compatibility

<!-- source: prettier/prettier | topic: API | language: JavaScript | updated: 2024-09-23 -->

When evolving public APIs, prioritize backward compatibility and avoid breaking changes to existing interfaces. Support both legacy and new syntax when standards evolve, and clearly document any deprecations.

Key practices:
- Preserve existing public API signatures even when internal implementation changes
- When new standards replace old ones (like import attributes vs assertions), support both syntaxes during transition periods
- Use feature detection and graceful fallbacks rather than removing legacy support immediately
- Add new functionality through optional parameters or separate methods rather than modifying existing signatures

Example from import syntax evolution:
```javascript
// Support both new and legacy syntax
const importAttributesPlugins = ["importAttributes", "importAssertions"];

// Or use parser options to handle both
const keyword = property === "assertions" || node.extra?.deprecatedAssertSyntax ? "assert" : "with";
```

This approach ensures that existing code continues to work while allowing adoption of newer standards, reducing friction for API consumers and maintaining ecosystem stability.

---

## Complete deployment commands

<!-- source: vitejs/vite | topic: CI/CD | language: Markdown | updated: 2024-09-19 -->

Always ensure build commands in CI/CD configurations include all necessary steps for successful deployment, particularly dependency installation. Incomplete commands are a common source of deployment failures.

For platform-specific deployments (like Render), use the complete sequence of commands:

```
npm install && npm run build
```

Rather than incomplete commands:

```
npm run build
```

This ensures dependencies are installed before the build process begins, preventing failures due to missing packages in clean CI environments.

---

## Minimize lock duration

<!-- source: vercel/turborepo | topic: Concurrency | language: Rust | updated: 2024-09-16 -->

When using locks in asynchronous code, minimize the scope and duration for which locks are held, especially across `.await` points. Holding locks during asynchronous operations can block progress in other tasks and lead to decreased concurrency or even deadlocks.

Always follow these practices:
1. Acquire locks in the smallest possible scope
2. Release locks as soon as the protected operation is complete
3. Never hold locks across I/O or other long-running async operations

```rust
// Bad: Lock held during potentially long-running operation
let changed_packages_guard = changed_packages.lock().await;
if !changed_packages_guard.borrow().is_empty() {
    let changed_packages = changed_packages_guard.take();
    self.execute_run(changed_packages).await?; // Lock still held during execution
}

// Good: Lock released after data extraction
let some_changed_packages = {
    let mut changed_packages_guard = changed_packages.lock().await;
    (!changed_packages_guard.is_empty())
        .then(|| std::mem::take(changed_packages_guard.deref_mut()))
};
if let Some(changed_packages) = some_changed_packages {
    self.execute_run(changed_packages).await?; // Lock already released
}
```

This pattern is particularly crucial when dealing with I/O operations, network requests, or UI updates, as these operations may take significant time to complete. Using scope blocks to manage lock lifetimes ensures other concurrent operations can make progress while long-running tasks execute.

---

## Decouple CI from code

<!-- source: Homebrew/brew | topic: CI/CD | language: Shell | updated: 2024-09-11 -->

Separate CI configuration from code that serves other purposes. When variables or settings affect both user-facing behavior and CI pipeline behavior, extract CI-specific logic into dedicated configuration files. This prevents unintended CI pipeline changes when updating user-facing functionality and allows for better coordination between code changes and CI environment updates.

For example, instead of:
```bash
# This controls both user warnings and CI runners
HOMEBREW_MACOS_OLDEST_SUPPORTED="13"
```

Refactor to:
```bash
# User-facing support declaration
HOMEBREW_MACOS_OLDEST_SUPPORTED="13"

# CI configuration in a separate file (github_runner_matrix.rb)
HOMEBREW_CI_MACOS_VERSIONS = ["13", "14"]
```

This separation allows you to control the timing of CI environment changes independently from feature changes, ensuring proper sequencing of: code changes, release tagging, and then CI environment updates.

---

## Escape HTML content properly

<!-- source: vitejs/vite | topic: Security | language: TypeScript | updated: 2024-09-10 -->

Always use specialized HTML escaping functions when outputting dynamic content to prevent Cross-Site Scripting (XSS) vulnerabilities. Don't rely on general serialization methods like JSON.stringify which may not correctly escape all HTML-sensitive characters or may add unnecessary escapes.

When working with HTML attribute values:

```javascript
// Incorrect: Using JSON.stringify for HTML attributes
res += ` ${key}=${JSON.stringify(attrs[key])}`

// Correct: Using dedicated HTML escaping
res += ` ${key}="${escapeHtml(attrs[key])}"`
```

This approach ensures all potentially dangerous characters are properly escaped before being inserted into HTML, preventing script injection attacks while avoiding unnecessary character escaping that could affect functionality or readability.

---

## Handle errors appropriately

<!-- source: vercel/turborepo | topic: Error Handling | language: TypeScript | updated: 2024-09-09 -->

Implement appropriate error handling strategies based on the criticality of operations. For non-critical operations that could fail (like file operations and JSON parsing), use try/catch blocks to handle errors gracefully and continue execution with proper logging. For critical operations where execution cannot reasonably continue, provide clear error messages and abort.

**Good example:**
```typescript
// When reading files that might not exist
try {
  const config = readJsonSync(configPath);
  // Process config
} catch (error) {
  // Log the error
  debug(`Error reading config: ${error.message}`);
  // Continue with fallback or degraded functionality if appropriate
  config = defaultConfig;
}

// For critical operations
try {
  const packageJSON = readJsonSync(packageJsonPath);
  if (!packageJSON) {
    log.error("Critical error: Could not read package.json");
    return { success: false, error: "Missing required package.json" };
  }
} catch (error) {
  log.error(`Failed to parse package.json: ${error.message}`);
  return { success: false, error: "Invalid package.json" };
}
```

Be defensive with operations that might fail, but make intentional decisions about whether to continue execution based on the criticality of the error. Always provide clear error messages and sufficient context for debugging.

---

## Evolve APIs with compatibility

<!-- source: vitejs/vite | topic: API | language: TypeScript | updated: 2024-09-03 -->

When evolving APIs, maintain backwards compatibility while introducing new features by following a staged deprecation approach:

1. Introduce new APIs alongside existing ones without deprecation warnings
2. Enable opt-in deprecation warnings in minor versions
3. Add breaking changes behind feature flags
4. Remove deprecated features in major versions

Example:
```typescript
// Stage 1: Add new API alongside existing
interface Config {
  // Existing API
  ssrLoadModule(url: string): Promise<Module>
  
  // New API
  environments: {
    ssr: {
      moduleGraph: ModuleGraph
      loadModule(url: string): Promise<Module>
    }
  }
}

// Stage 2: Add deprecation warning system
interface FutureOptions {
  deprecationWarnings?: boolean | {
    ssrLoadModule?: boolean
  }
}

// Stage 3: Feature flags for breaking changes
interface Config {
  future?: {
    // Opt-in to new behavior
    useEnvironmentAPI?: boolean
  }
}
```

This approach allows users to migrate at their own pace while maintaining a clear upgrade path. Document both old and new APIs until deprecation is complete, and provide migration guides that explain the benefits of new approaches.

---

## avoid raw injection

<!-- source: likec4/likec4 | topic: Security | language: TSX | updated: 2024-09-01 -->

{% raw %}
When generating and inserting HTML or CSS as raw strings, treat it as untrusted input and avoid direct injection into the DOM. Constructing <style> tags or innerHTML from dynamic values can enable XSS if any part of those values is attacker-controlled.

Guidance:
- Prefer safe APIs:
  - Use React props/style or CSS variables on elements instead of creating raw <style> blocks from strings.
  - Validate and constrain any identifiers (e.g., CSS selectors, data-* attributes) and color/value formats before use.
- If you must insert raw HTML/CSS, do so explicitly and sanitize:
  - Use a well-maintained HTML/CSS sanitizer (e.g., DOMPurify for HTML) or rigorous validation for CSS values.
  - Use dangerouslySetInnerHTML only with a sanitized string and a code comment explaining why injection is necessary.
- Add code review attention and, where applicable, a unit test asserting sanitized output or allowed-value enforcement.

Examples:
// Unsafe: building a <style> string from external input (risky)
const styles = Object.entries(customColors).map(([name, color]) => `:where([data-likec4-color=${name}]) { --clr: ${color}; }`).join('\n');
return <style>{styles}</style>; // avoid this unless input is fully trusted

// Safer: set CSS variables on elements (no raw HTML injection)
// For each themed container element:
<div data-likec4-color={name} style={{ ['--likec4-color' as any]: color }} />

// If injection is required, sanitize and document
import DOMPurify from 'dompurify';
const safe = DOMPurify.sanitize(styles, {ALLOWED_TAGS: ['style'], ALLOWED_ATTR: []});
return <style dangerouslySetInnerHTML={{ __html: safe }} />; // include comment why injection is necessary

Why this matters: Unescaped or unsanitized content inserted into the DOM can enable XSS or CSS injections. Using safe APIs, validation, or vetted sanitization prevents class of security vulnerabilities and makes intent explicit during code review.
{% endraw %}

---

## Use affected mode

<!-- source: vercel/turborepo | topic: CI/CD | language: Other | updated: 2024-08-28 -->

Optimize CI pipelines by running tasks only on packages affected by code changes. Use the `--affected` flag in Turborepo commands to automatically filter tasks to packages with changes, significantly reducing CI execution time in large monorepos.

```bash
# Run build only on affected packages
turbo run build --affected

# Specify custom base branch for comparison
TURBO_SCM_BASE=development turbo run test --affected
```

By default, affected mode compares changes between `main` and `HEAD`. Override these defaults with environment variables `TURBO_SCM_BASE` and `TURBO_SCM_HEAD` when needed, such as when working with feature branches or alternative main branches.

Ensure your checkout has sufficient history depth; shallow clones may cause all packages to be considered changed. This approach ensures CI resources are used efficiently by focusing only on what changed, preventing unnecessary builds and tests while maintaining comprehensive validation.

---

## Organize code for readability

<!-- source: bazelbuild/bazel | topic: Code Style | language: Python | updated: 2024-08-26 -->

Structure code to minimize complexity and improve readability through logical organization. This includes using early returns to reduce nesting levels and ordering operations in a logical sequence.

Use early returns to flatten code structure and avoid deep nesting:

```python
# Prefer this - early return pattern
if argv[1] != "get":
    eprint("Unknown command ...")
    return 1

# Handle main logic here
...

# Instead of nested if-else chains
if argv[1] == "get":
    # Handle main logic here
    ...
else:
    eprint("Unknown command ...")
    return 1
```

Additionally, organize method calls in logical order where setup operations precede execution operations:

```python
# Setup first
self.ScratchFile('BUILD', [...])
self.ScratchFile('main.cc', [...])

# Then execute
exit_code, _, stderr = self.RunBazel([...])
```

This approach reduces cognitive load by keeping indentation shallow and presenting operations in their natural sequence.

---

## Pin Actions SHAs

<!-- source: mermaid-js/mermaid | topic: Security | language: Yaml | updated: 2024-08-24 -->

For security-sensitive CI workflows, pin third-party GitHub Actions to immutable commit SHAs (not floating tags like `v3`/`v4`). This prevents supply-chain risk from upstream tag changes. Use Dependabot (or equivalent) to keep pinned SHAs updated automatically.

Example (pinned):
```yml
- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
- uses: hadolint/hadolint-action@54c9adbab1582c2ef04b2016b760714a4bfde3cf # v3.1.0
```

Avoid (unpinned/mutable):
```yml
- uses: actions/checkout@4
- uses: hadolint/hadolint-action@3.1.0
```

---

## Link terms, provide examples

<!-- source: vercel/turborepo | topic: Documentation | language: Other | updated: 2024-08-18 -->

When writing technical documentation, link to related concepts the first time they are mentioned, and include concrete examples to illustrate complex features or functionality.

When introducing a term or concept:
1. Link to its definition or more detailed explanation on its first occurrence
2. Include practical examples when explaining features or configurations
3. Consider the reader's perspective - what might be unclear to someone unfamiliar with the system?

**Example:**

```markdown
// Less helpful:
Turborepo's Environment Modes allow you to control which environment variables are available to a task at runtime.

// More helpful:
[Turborepo's Environment Modes](/repo/docs/core-concepts/environment-variables) allow you to control which environment variables are available to a task at runtime. For example:

```json
{
  "envMode": "strict",
  "env": ["API_KEY", "DEBUG"]
}
```
```

This approach helps readers immediately access relevant context without needing to search for it, and concrete examples make abstract concepts easier to understand and implement.

---

## Use descriptive variable names

<!-- source: prettier/prettier | topic: Naming Conventions | language: JavaScript | updated: 2024-08-16 -->

Choose variable and function names that clearly communicate their purpose, type, and context. Avoid abbreviations, overly generic terms, and names that could be confused for different types.

Key principles:
- **Communicate intent**: Use `array` instead of `xs`, `whitespaceCharacters` instead of `characters`
- **Indicate type when ambiguous**: Use `shouldCache` for booleans instead of `cache`, `clonedNode` instead of `clone` (which sounds like a function)
- **Be appropriately specific**: Use `createCachedSearchFunction` instead of the too-generic `createCachedFunction`, `isPrevNodeMarkdownlintComment` instead of `isPrevNodeSpecificComment`
- **Include context in method names**: Use `splitByContinuousWhitespace` instead of just `split`

Example improvements:
```javascript
// Before: unclear and generic
function chunk(xs, chunkSize) { ... }
const cache = new Map();
function createCachedFunction(function_) { ... }

// After: descriptive and clear
function chunk(array, size) { ... }
const shouldCache = true;
function createCachedSearchFunction(searchFunction) { ... }
```

This approach makes code self-documenting and reduces the cognitive load for other developers reading and maintaining the code.

---

## Use JSDoc deprecation standards

<!-- source: vercel/turborepo | topic: Documentation | language: TypeScript | updated: 2024-08-15 -->

When marking code as deprecated, use JSDoc standards to provide clear guidance for developers. Always use the `@deprecated` tag followed by when it was deprecated and what should be used instead. Additionally, use the `{@link}` tag to create clickable references to replacement functionality.

Example:
```typescript
/**
 * @deprecated as of Turborepo 2.0.0. Consider using {@link RootSchema.globalDependencies} instead.
 */
export interface SomeDeprecatedInterface {
  // ...
}
```

This approach creates clickable references in many IDEs and documentation tools, allowing developers to quickly navigate to the recommended alternatives. Proper deprecation documentation helps with code maintenance and reduces confusion during migration to newer APIs.

---

## Choose logging levels wisely

<!-- source: vercel/turborepo | topic: Logging | language: Rust | updated: 2024-08-13 -->

Select appropriate logging levels based on the frequency and importance of the logged operation. Use `trace` for high-frequency operations (e.g., operations executed once per package or file) to prevent log noise at lower verbosity levels, and reserve `debug` for less frequent, more significant events or aggregated information.

Include relevant context in log messages to make them actionable:

```rust
// Less useful - lacks context
debug!("files to cache: {:?}", files_to_be_cached.len());

// More useful - includes task identifier
debug!("{}: files to cache: {:?}", self.task_id, files_to_be_cached.len());

// For high-frequency operations, use trace
trace!("loading package.json from {}", path);
```

By thoughtfully selecting logging levels and providing context, you create logs that are both informative when needed and not overwhelming during regular operation. This enables effective debugging without drowning developers in noise when using increased verbosity.

---

## Use descriptive names

<!-- source: prettier/prettier | topic: Naming Conventions | language: Markdown | updated: 2024-08-13 -->

Choose names that clearly communicate purpose and meaning rather than implementation details or obscure abbreviations. Names should be easily understood by other developers and reflect what the identifier actually represents or does.

For function parameters, use names that describe the data's role in the function rather than its source or format. For documentation and labels, prefer commonly understood terminology that developers can easily search for and recognize.

```javascript
// Avoid: implementation-focused names
function getPreferredQuote(rawContent: string) { ... }

// Prefer: purpose-focused names  
function getPreferredQuote(text: string) { ... }

// Avoid: obscure abbreviations
JS(ESM):

// Prefer: clear, searchable terms
JS (ES Modules):
```

This approach improves code readability, makes documentation more discoverable, and helps other developers quickly understand the purpose of variables, functions, and parameters.

---

## Organize tests properly

<!-- source: prettier/prettier | topic: Testing | language: JavaScript | updated: 2024-07-26 -->

Tests should be well-structured with clear separation of concerns, proper grouping, and appropriate cleanup mechanisms. Separate different types of tests (performance vs functional), use descriptive test blocks, and ensure proper isolation to prevent side effects between tests.

Key practices:
- Separate performance tests from functional tests to avoid environment-dependent failures
- Use nested describe blocks to group related test cases logically
- Implement proper cleanup in finally blocks when tests modify global state
- Structure tests with clear "Invalid usage" and "Valid usage" sections when testing both scenarios

Example structure:
```js
describe("doc builders", () => {
  test("Invalid usage", () => {
    // test invalid scenarios
  });
  test("Valid usage", () => {
    // test valid scenarios  
  });
});

test("node version error", async () => {
  const originalProcessVersion = process.version;
  try {
    Object.defineProperty(process, "version", { value: "v8.0.0" });
    const result = await runPrettier("cli", ["--help"]);
    // assertions
  } finally {
    Object.defineProperty(process, "version", { 
      value: originalProcessVersion 
    });
  }
});
```

This approach prevents test pollution, improves maintainability, and ensures reliable test execution across different environments.

---

## Document network interface purposes

<!-- source: bazelbuild/bazel | topic: Networking | language: Java | updated: 2024-07-26 -->

When implementing multiple network-related interfaces or classes that handle similar operations (like downloading), clearly document the purpose, scope, and differences between each interface to prevent confusion and misuse.

This is particularly important when you have specialized implementations for different protocols or use cases. For example, if you have both a general `Downloader` interface and a specialized `HttpDownloader` class, or when introducing remote download proxies like `GrpcRemoteDownloader`, each should have clear documentation explaining:

- What specific use cases each interface/class serves
- Why multiple interfaces are needed instead of a unified approach  
- Which methods are available on which interfaces
- How they interact with configuration flags and different execution contexts

Example from the codebase:
```java
public DownloadManager(
    RepositoryCache repositoryCache, 
    Downloader downloader, 
    HttpDownloader httpDownloader) {
  // Document why we need both Downloader and HttpDownloader:
  // - Downloader: General interface, may be GrpcRemoteDownloader for remote asset API
  // - HttpDownloader: Direct HTTP implementation, used by bzlmod for registry access
  // - The bzlmod downloader uses downloadAndReadOneUrl() which only exists on HttpDownloader
}
```

This prevents developers from having to reverse-engineer the differences between interfaces and reduces the likelihood of using the wrong interface for a given use case. It also helps during code reviews to ensure the appropriate download mechanism is being used for each context.

---

## Benchmark performance optimizations

<!-- source: prettier/prettier | topic: Performance Optimization | language: Markdown | updated: 2024-07-22 -->

Always measure and validate performance optimizations with concrete benchmarks before implementing them. Performance assumptions can be misleading, and minor gains may not justify added complexity or reduced correctness.

When considering performance optimizations:
1. Create reproducible benchmarks to measure actual impact
2. Test across different scenarios and project sizes
3. Consider whether the performance gain justifies any tradeoffs in correctness, maintainability, or user experience
4. Be willing to remove optimizations that don't provide meaningful benefits

Example from caching strategy evaluation:
```bash
# Benchmark showed minimal difference despite expectations
--cache-strategy=metadata x 0.30 ops/sec ±6.05% (5 runs sampled)
--cache-strategy=content x 0.30 ops/sec ±0.94% (5 runs sampled)

# Decision: Choose content strategy despite 10-20ms cost
# Reason: "For normal projects, there is no performance difference, 
# and content is more convenient"
```

Avoid premature optimization and be prepared to prioritize correctness and usability over marginal performance gains. If benchmarks show negligible differences, choose the option that provides better developer experience or system reliability.

---

## Angular syntax parsing

<!-- source: prettier/prettier | topic: Angular | language: JavaScript | updated: 2024-07-13 -->

When implementing Angular syntax parsing, ensure robust handling of Angular-specific constructs by properly distinguishing AST node types and normalizing flexible syntax patterns.

For AST visitor keys, only include actual Node objects, not primitive values:
```javascript
// Correct - empty array since name and value are strings, not nodes
angularLetDeclaration: [],

// Incorrect - includes non-node primitives
angularLetDeclaration: ["name", "value"],
```

For Angular control flow blocks, normalize whitespace in block names to handle flexible syntax:
```javascript
// Should handle both:
@else if () {}        // standard spacing
@else   if () {}      // flexible whitespace

// Implementation should normalize "else   if" → "else if"
```

This ensures the parser correctly processes Angular's flexible syntax while maintaining proper AST structure for tooling compatibility.

---

## File-specific indentation standards

<!-- source: octokit/octokit.net | topic: Code Style | language: Json | updated: 2024-06-29 -->

Maintain consistent indentation based on file type to ensure code readability and prevent unwanted whitespace changes in PRs. Use 4 spaces for C# (.cs) files and 2 spaces for configuration files (like JSON, devcontainer files).

Example for C# files:
```csharp
public class Example 
{
    public void Method() 
    {
        if (condition) 
        {
            DoSomething();
        }
    }
}
```

Example for configuration files:
```json
{
  "name": "Project",
  "settings": {
    "editor.tabSize": 4,
    "editor.insertSpaces": true
  }
}
```

When working in different editors, ensure your editor settings reflect these standards. Configure IDE settings on a per-language basis (e.g., in VSCode settings.json) to automatically apply the correct indentation for each file type. This prevents accidental reformatting and maintains consistency throughout the codebase.

---

## Automate sensitive CI artifacts

<!-- source: bazelbuild/bazel | topic: CI/CD | language: Other | updated: 2024-06-21 -->

Large files and security-sensitive artifacts should be automatically generated in CI/CD pipelines rather than manually committed to version control. This reduces security risks from potentially malicious content and ensures artifacts stay current with the codebase.

For large profile files or binary artifacts, implement automated generation through CI jobs or release pipelines:

```python
# Instead of committing large profile files directly
# Use CI to regenerate profiles automatically
def regenerate_profile():
    # Run profiling in controlled CI environment
    bazel run //tools:profile_generator
    # Output profile as build artifact
```

Additionally, follow organizational policies for dependency placement. Files that could create bundling dependencies should be placed in appropriate directories (like `tools/` instead of `third_party/`) and explicitly documented:

```python
# Move sensitive configs to policy-compliant locations
# tools/proguard/config.proguard instead of third_party/
# Add to exclude lists to document the choice
exclude = ["tools/proguard/config.proguard"]
```

This approach ensures CI/CD security, maintains compliance with organizational policies, and keeps sensitive artifacts synchronized with code changes through automation.

---

## API input/output validation

<!-- source: hyprwm/Hyprland | topic: API | language: C++ | updated: 2024-06-19 -->

Ensure robust parsing of API inputs and proper formatting of outputs to prevent parsing errors and unexpected behavior. API implementations must handle edge cases where command identifiers might appear within parameter values, and all output formats must properly escape special characters.

For input parsing, avoid simple substring matching that could incorrectly identify commands within parameter data. For example, a command like `/notify blah blah /decorations` should be parsed as the `/notify` command with `/decorations` as part of the parameter string, not as a `/decorations` command.

For output formatting, always escape special characters in structured formats like JSON:

```cpp
// Bad - missing escaping
result += std::format(R"#("{}",)#", current);

// Good - with proper escaping  
result += std::format(R"#("{}",)#", escapeJSONStrings(current));
```

This prevents client-side parsing failures when API responses contain quotes, newlines, or other special characters. Implement comprehensive input validation and output sanitization as fundamental requirements for all API endpoints.

---

## Document build configurations

<!-- source: astral-sh/uv | topic: Configurations | language: Dockerfile | updated: 2024-05-05 -->

When setting Rust build configurations, especially in CI/Docker environments, explicitly document optimization choices and their tradeoffs. Consider whether configurations should live in Cargo.toml, .cargo/config.toml, or as environment variables in CI scripts. For Docker builds, document RUSTFLAGS options like optimization levels, relocation models, and linking settings, along with their impact on binary size, performance, and security. Ensure consistency between Docker build commands and any custom profiles defined in project files.

```Dockerfile
# Document optimization choices and tradeoffs
ARG RUSTFLAGS="-C strip=symbols -C relocation-model=static -C target-feature=+crt-static -C opt-level=z"
# strip=symbols: Reduces binary size
# relocation-model=static: Reduces size at expense of ASLR security
# target-feature=+crt-static: Ensures fully static linking
# opt-level=z: Optimizes for size; benchmark to assess performance impact

# Ensure consistency with any custom profiles in Cargo.toml
RUN cargo build --release  # Uses custom profile if defined in Cargo.toml
```

---

## prefer early returns

<!-- source: alacritty/alacritty | topic: Code Style | language: Rust | updated: 2024-05-03 -->

Use early returns and guard clauses to reduce nesting levels and improve code readability. When you have multiple conditional branches or error conditions, return early from the function rather than creating deeply nested if-else structures.

This pattern is especially beneficial when dealing with:
- Error conditions that should terminate execution
- Simple boolean conditions where one branch is just `false` or empty
- Multiple validation steps
- Complex conditional logic with 4+ levels of indentation

Example of improvement:
```rust
// Instead of deeply nested conditions:
fn process_data(data: &str) -> Result<String, Error> {
    if !data.is_empty() {
        if data.len() > 10 {
            if data.starts_with("valid") {
                // 4 levels of indentation - hard to read
                Ok(data.to_uppercase())
            } else {
                Err(Error::InvalidPrefix)
            }
        } else {
            Err(Error::TooShort)
        }
    } else {
        Err(Error::Empty)
    }
}

// Use early returns for cleaner code:
fn process_data(data: &str) -> Result<String, Error> {
    if data.is_empty() {
        return Err(Error::Empty);
    }
    
    if data.len() <= 10 {
        return Err(Error::TooShort);
    }
    
    if !data.starts_with("valid") {
        return Err(Error::InvalidPrefix);
    }
    
    Ok(data.to_uppercase())
}
```

This approach reduces cognitive load by handling edge cases upfront and keeping the main logic at a consistent indentation level. It also makes the function's requirements and error conditions immediately clear to readers.

---

## Precise configuration patterns

<!-- source: hyprwm/Hyprland | topic: Configurations | language: Txt | updated: 2024-05-02 -->

Use precise file patterns and correct installation paths in CMake configuration to avoid unintended inclusions and ensure proper system integration. Overly broad patterns can consume unrelated files from subprojects, while incorrect paths can break package discovery.

Key practices:
- Scope file globbing patterns appropriately (e.g., `src/*.h*` instead of `*.h*`)
- Use standard CMake modules like `GNUInstallDirs` for installation paths
- Specify precise file patterns in install commands with exclusions when needed
- Validate installation destinations match expected system conventions

Example of precise pattern usage:
```cmake
# Bad - too broad, includes subprojects
file(GLOB_RECURSE HEADERS_HL CONFIGURE_DEPENDS "*.h*")

# Good - scoped to source directory
file(GLOB_RECURSE HEADERS_HL CONFIGURE_DEPENDS "src/*.h*")

# Good - precise pattern with exclusions
install(DIRECTORY protocols/ DESTINATION include/hyprland/protocols 
        FILES_MATCHING PATTERN "*.h")

# Good - using standard CMake variables
install(TARGETS Hyprland hyprctl DESTINATION ${CMAKE_INSTALL_BINDIR})
```

This prevents build system confusion, ensures clean installations, and maintains compatibility across different environments and package managers.

---

## Configuration documentation accuracy

<!-- source: alacritty/alacritty | topic: Configurations | language: Other | updated: 2024-04-30 -->

Ensure configuration documentation is accurate, consistent, and clearly indicates optional versus required values. Use consistent terminology throughout documentation, provide accurate technical details, and make examples actionable for developers.

Key practices:
- Use consistent language when describing configuration behavior (e.g., "looks for" vs "should be located at")
- Accurately document default values and optional parameters, explicitly showing when values can be "None"
- Ensure technical details like Unicode ranges, data types, and formatting are correct
- Make examples directly usable by developers: "Every _Default:_ and _Example:_ entry is valid TOML and can be copied directly into the configuration file"
- Use proper formatting conventions consistently across all documentation

Example of good documentation structure:
```
*position* "None" | { x = <integer>, y = <integer> }

    Window startup position

    Specified in number of pixels.

    If the position is _"None"_, the window manager will handle placement.
    
    Default: _"None"_
```

This approach helps developers understand exactly what configuration options are available, what values are valid, and how to properly use them in their own configurations.

---

## Explicit API shapes

<!-- source: wavetermdev/waveterm | topic: API | language: TypeScript | updated: 2024-04-26 -->

Require API surfaces (payloads, function contracts, and compact descriptor grammars) to be explicit, well-documented, and normalized at the boundary. This reduces client/server surprises, clarifies intent (single vs collection), and ensures deterministic parsing.

Guidelines
- Names and shapes: use names that reveal type and multiplicity. Prefer pluralized fields for arrays (and document element type). Example: change a singular ambiguous field:
  // before
  if ("screenstatusindicator" in update) { /* ... */ }
  // after
  if ("screenstatusindicators" in update) {
    for (const indicator of update.screenstatusindicators) { /* ... */ }
  }
  Rationale: clients and servers immediately know to expect a list; use const in iteration to avoid accidental reassignment.

- Method contracts and side effects: document whether higher-level calls encapsulate sub-operations and whether they early-return. If a wrapper may return early and skip sub-effects, provide an explicit API to perform the sub-effect or call that explicit API when you require it. Example:
  // If setActiveAuxView may return early and not call setAuxViewFocus, call setAuxViewFocus explicitly
  this.setActiveAuxView(appconst.InputAuxView_AIChat);
  this.setAuxViewFocus(true);
  Or, if the higher-level API guarantees the behavior, prefer the single call that documents the intent:
  this.inputModel.setAuxViewFocus(false); // if it calls giveFocus internally

- Input grammar & normalization: design compact descriptor formats (e.g., keyboard descriptions) with a small formal grammar, parse to structured objects, and normalize values at the boundary. Document the grammar and make parsing Unicode-aware.
  Example grammar idea (from discussions):
  - Use ':' to separate ordered sequence, and '|' to express alternatives for modifier groups.
  - ctrl:shift:c  -> ["ctrl","shift","c"]
  - ctrl|opt:c    -> [["ctrl","opt"], "c"]
  Parsing should return structured shapes (arrays/nested arrays) and normalize key names (e.g., accept " "/"Space" and map to "Space"). Use Unicode-aware checks for letter casing (e.g., /\p{Lu}/u or with the 'v' flag where supported) when inferring Shift.

- Documentation and tests: document contract, examples, and edge cases in the API docs. Add tests for: plural vs singular payloads, early-return behavior, descriptor parsing (including Unicode characters), and normalization rules.

Why this matters
- Clear shapes reduce client/server mismatch and versioning confusion.
- Explicit side-effect contracts prevent subtle bugs where callers assume sub-actions run but they do not.
- Formalized grammars and normalization produce deterministic behavior across locales and platforms.

Apply this rule when defining REST/IPC payloads, library public methods, or compact descriptor syntaxes so client code can rely on stable, well-documented interfaces.

---

## Centralize constants and structure

<!-- source: wavetermdev/waveterm | topic: Code Style | language: Go | updated: 2024-04-17 -->

Motivation
Keep code readable, consistent and easy to change by centralizing configuration, constants and mutable state, and by extracting repeated flows into well-scoped helpers or service types.

Rules
- Move literal paths and long user-facing strings to package-level consts in the appropriate package (e.g., base or config). Don’t inline repeated strings. Example:
  // in base.go
  const ConfigDir = "config"
  const AIUseTelemetryMsg = `In order to protect against abuse, you must have telemetry turned on ...`
  // usage
  fullPath := path.Join(scbase.GetWaveHomeDir(), ConfigDir, filePath)

- Replace package-level mutable globals with concrete types that implement interfaces. This enables multiple instances, easier testing, and clearer ownership of state. Example:
  // instead of package globals:
  // var cache map[string]*CacheEntry

  type BlockStoreType struct {
    mu    sync.Mutex
    cache map[string]*CacheEntry
    // other fields
  }

  func NewBlockStore() *BlockStoreType { return &BlockStoreType{cache: map[string]*CacheEntry{}} }

  // implement BlockStore methods on *BlockStoreType

- Remove boilerplate by extracting common flows into helpers or central services. If multiple code paths perform the same multi-step operation (e.g., copying files between remotes and writing to PTY), consolidate into a single function or route through a central component (mshell). This reduces duplicate writeStringToPty calls and branching.
  Example:
  // high-level helper
  func copyFileRemoteToRemote(ctx context.Context, src RemoteRef, dst RemoteRef, opts CopyOpts) error { /* unified logic */ }

  // caller becomes a small orchestration wrapper
  err := copyFileRemoteToRemote(ctx, sourceRemoteId, destRemoteId, opts)

- Prefer idiomatic, simple APIs when building payloads or encoding. For JSON request payloads, use json.Marshal to get []byte directly instead of manual bytes.Buffer + Encoder when appropriate:
  payload, err := json.Marshal(cloudCompletionRequestConfig)
  if err != nil { return err }
  req, _ := http.NewRequest("POST", url, bytes.NewReader(payload))

Application guidance
- Put constants in logical packages (base/config for paths, a strings or msgs package for long messages if reused across files).
- When you spot repeated sequences of statements (logging + pty writes + connection attempts), factor them into a single helper and add tests for that helper.
- When a package uses mutable shared state, prefer wrapping it in a type with methods and constructors (NewX) and keep package-level variables minimal.
- Small, local refactors that centralize behavior are preferred over ad-hoc fixes scattered across files.

Why this matters
Centralizing constants and state improves discoverability and reduces risk when changing behavior (e.g., renaming the config directory or changing a long message). Extracting repeated logic reduces bugs and makes reasoning/test coverage easier. Using idiomatic APIs keeps code concise and consistent.

References: 0,1,2,3,4

---

## Centralize database operations

<!-- source: wavetermdev/waveterm | topic: Database | language: Go | updated: 2024-04-17 -->

Keep all SQL and DB-specific logic in a single dbops layer and expose a small, consistent API that handles common patterns: insert/update (use REPLACE/UPSERT), delete, queries, and serialization of complex fields. Motivation: reduces duplicated SQL across packages, avoids mismatch between INSERT vs UPDATE code paths, and centralizes serialization/transaction handling for sqlite or other stores.

How to apply (practical steps):
- Move DB functions (e.g., InsertFileIntoDB, WriteFileToDB, SetReleaseInfo) into a dbops package/file. Callers should pass typed objects; dbops performs SQL and serialization.
- Provide an upsert helper using REPLACE or an explicit UPSERT clause so you don't keep separate Insert vs Update functions:

Example (replace separate insert/update with REPLACE):
query := `REPLACE INTO block_file VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
// tx.Exec(query, fileInfo.BlockId, fileInfo.Name, fileInfo.Opts.MaxSize, fileInfo.Opts.Circular, fileInfo.Size, fileInfo.CreatedTs, fileInfo.ModTs, metaJson)

- Centralize JSON serialization/deserialization: implement and reuse a small helper (quickJson/quickJSONEncode) for storing complex fields in sqlite to ensure consistent encoding and error handling. Example:

metaJson, err := quickJson(fileInfo.Meta)
if err != nil {
    return fmt.Errorf("error serializing meta for %s: %w", fileInfo.Name, err)
}
// then use metaJson in the REPLACE/UPSERT

- Keep transactions and error mapping in dbops: wrap DB operations with WithTx inside dbops so callers don't duplicate transaction boilerplate.

Checklist for changes:
- [ ] Create/extend dbops package and move DB functions there.
- [ ] Add Upsert/Replace helpers and use them for insert-or-update semantics.
- [ ] Add quickJson/quickJSONEncode and decode helpers; use them everywhere complex fields are stored.
- [ ] Update callers to use dbops API and remove in-package SQL code.

Benefit: clearer separation of concerns, fewer duplicated SQL code paths, consistent serialization, and easier maintenance and optimization of queries.

---

## Config precedence

<!-- source: wavetermdev/waveterm | topic: Configurations | language: Go | updated: 2024-04-16 -->

Establish a clear configuration precedence and control policy: explicit user-supplied settings take priority over automatic detection, unless a centralized policy (e.g., cloud/service-side limits or security constraints) explicitly disallows client overrides. Motivation: prevents surprising behavior while allowing deliberate overrides and enforcing safety/consistency where needed.

How to apply:
- Rule order: 1) explicit per-request or per-call arguments (when present) 2) persisted configuration (env vars/config files/feature flags) 3) automatic detection/fallbacks.
- Exception: for managed/cloud/back-end operations, enforce server-side defaults for sensitive or quota-related parameters and ignore client attempts to override them.

Examples:
- Respect explicit kwarg, otherwise detect:
  if _, ok := pk.Kwargs[KwArgSudo]; ok {
      runPacket.IsSudo = sudoArg // explicit override
  } else {
      runPacket.IsSudo = IsSudoCommand(cmdStr) // fallback detection
  }

- Enforce cloud defaults server-side (ignore client-specified tokens/choices):
  // do not trust opts.MaxTokens for cloud; set fixed values before sending
  cloudReq.MaxTokens = cloudDefaultMaxTokens
  cloudReq.MaxChoices = cloudDefaultMaxChoices

Documentation: record the precedence rules in the project config guide and call out contexts where server-side policies override client inputs. When changing behavior, log or document when a client-supplied value was ignored so callers can diagnose differences.

---

## Use cross-platform commands

<!-- source: prettier/prettier | topic: CI/CD | language: Markdown | updated: 2024-04-10 -->

When writing CI/CD scripts and documentation, prefer Node.js APIs over shell commands for file operations to ensure cross-platform compatibility. Shell commands like `echo "content" > file` don't work consistently across different operating systems, particularly Windows, which can cause CI/CD pipelines to fail.

Instead of using shell-specific commands, use Node.js built-in APIs that work uniformly across all platforms:

```bash
# Avoid - doesn't work on Windows
echo "npx lint-staged" > .husky/pre-commit

# Prefer - works on all platforms
node --eval "fs.writeFileSync('.husky/pre-commit','npx lint-staged\n')"
```

This approach ensures that setup scripts, pre-commit hooks, and other CI/CD automation work reliably regardless of the operating system where they're executed, reducing platform-specific failures and improving the developer experience across diverse development environments.

---

## Sanitize CSS values

<!-- source: wavetermdev/waveterm | topic: Security | language: TSX | updated: 2024-04-10 -->

When generating CSS from external data (JSON, user input, theme files), validate and sanitize both CSS property names and values before injecting them into style elements to prevent style-breaking input and XSS/style injection.

Motivation: Building CSS via string concatenation (e.g. `--term-${key}: ${value};`) can allow malicious or malformed keys/values to break the stylesheet or inject content. Use browser APIs and input validation to make this safe.

How to apply:
- Prefer CSSOM APIs instead of raw string injection: use element.style.setProperty(propertyName, value).
- Escape property names with CSS.escape when used in a context that requires serialization.
- Validate values with a whitelist or conservative regex: disallow characters that can break CSS such as `;`, `}` or HTML tag delimiters, and limit length. For colors/units consider explicit parsers or allowlists (hex colors, rgb(), numbers+units).
- If full fidelity is required, parse/serialize values using strict rules rather than passing arbitrary strings into a style element.

Example (adapted from the discussion):

// unsafe: `--term-${key}: ${value};`
// safer approach:
function isValidKey(key) {
  // allow lowercase letters, numbers, and hyphens (adjust to your naming rules)
  return /^[a-z0-9-]+$/.test(key);
}

function isValidValue(value) {
  if (typeof value !== 'string' || value.length > 200) return false;
  // disallow characters that can close or break CSS rules
  return !/[;{}<>]/.test(value);
}

async function applyTheme(themeJson, styleEl) {
  for (const [key, value] of Object.entries(themeJson)) {
    if (!isValidKey(key) || !isValidValue(String(value))) continue; // reject invalid entries

    // use CSS custom property API which avoids injecting raw CSS text
    // ensure the property name is valid per your rules
    styleEl.style.setProperty(`--term-${CSS.escape(key)}`, String(value));
  }
}

Notes:
- CSS.escape is broadly available and safe for serializing identifiers; still validate keys to match your naming expectations.
- For values that are colors or units, prefer strict parsing (e.g., validate hex, rgb(), or numeric+unit) rather than a permissive regex.
- When creating <style> text from dynamic data is unavoidable, ensure every key/value pair is validated and escaped, and avoid embedding untrusted HTML.

References: [0]

---

## Platform-specific API documentation

<!-- source: alacritty/alacritty | topic: Networking | language: Other | updated: 2024-03-28 -->

The provided discussions focus on terminal emulator documentation and configuration issues, but do not contain any content related to networking (network protocols, HTTP requests, TCP/IP, DNS, websockets, data transfer, network security, or connection management). 

The discussions cover platform-specific API behavior documentation, cross-platform command line handling, and documentation formatting - none of which relate to networking concepts. Therefore, no meaningful networking-related coding standard can be derived from these discussions.

The discussions would be more appropriate for categories like "Documentation Standards," "Cross-Platform Compatibility," or "Configuration Management" rather than "Networking."

---

## Document intent consistently

<!-- source: mermaid-js/mermaid | topic: Documentation | language: Other | updated: 2024-03-26 -->

When code changes affect how people understand or use behavior—especially grammar directives/annotations or feature support—add documentation that explains intent and keeps docs aligned with current functionality.

Apply this in two ways:
1) For non-obvious inline constructs (e.g., grammar annotations), add an immediate “what/why” comment so readers don’t need to infer meaning from implementation.
2) For user-facing feature support changes (e.g., removing directive support in favor of YAML frontmatter), ensure the relevant developer/user documentation is updated (or explicitly tracked via a follow-up PR) so there’s no mismatch between code and guidance.

Example (grammar annotation):
```text
terminal SANKEY_LINK_VALUE returns number: /"(0|[1-9][0-9]*)(\.[0-9]+)?"|.../;
/**
 * @greedy
 * This token should be matched late so it doesn’t preempt other token rules.
 */
@greedy
```

---

## Prefer semantic names

<!-- source: wavetermdev/waveterm | topic: Naming Conventions | language: TypeScript | updated: 2024-03-22 -->

Make identifiers convey intent: include meaningful domain fields in types and choose function names that reflect user-facing semantics (not internal storage order). When internal representation differs from user expectations (for example newest items appended to the end, but UI cycles newest-first), rename functions to express the user direction and add a brief inline comment explaining the storage-order invariant.

Why: Names and exposed type fields are primary documentation for future readers. Including key identifiers (e.g., command, info) in interfaces and using semantic method names reduces confusion and prevents subtle bugs or tech debt.

How to apply (practical rules):
- Types/interfaces should carry domain identifiers used by callers and UIs. If the UI needs the command name, include it on the config type.
  Example: type KeybindConfig = { command: string; keys: string[]; commandStr?: string; info?: string };
- Name methods for intent: prefer names that describe what the caller wants (selectNewest, selectPreviousInChat, moveToNextHistory), not how it is stored (increment/decrement).
  Example: instead of incrementCodeSelect() (ambiguous), use setCodeSelectSelectedCodeBlockPrevious() or selectPreviousCodeBlock(), depending on preferred style.
- When storage order is inverted relative to UI order, add a short comment describing the invariant and rationale next to the data structure or the renamed methods so future readers won’t be surprised.
  Example comment: // codeSelectBlockRefArray stores blocks oldest->newest; UI cycles newest-first, so selectPreviousCodeBlock() moves index -1 to show the block above in the chat.
- If renaming is infeasible, ensure the name and comment together make the direction explicit (e.g., decrement selects the newer item). Keep names and comments synchronized when behavior changes.

Benefits: clearer types for consumers, fewer accidental misuse and less cognitive load when reasoning about ordering and behavior, reduced tech debt because intent is explicitly encoded in names and small comments.

---

## Correct GitHub Actions annotations

<!-- source: Homebrew/brew | topic: CI/CD | language: Ruby | updated: 2024-03-14 -->

When using GitHub Actions workflow commands for annotations, always include double colons in the syntax (::command::). Proper formatting ensures warnings and errors are correctly displayed in the GitHub Actions UI and processed by workflow runners.

Example:
```ruby
# Correct
puts "::warning::#{message_full}" if ENV["GITHUB_ACTIONS"]
puts "::error::#{message_full}" if ENV["GITHUB_ACTIONS"]

# Incorrect
puts "::warning #{message_full}" if ENV["GITHUB_ACTIONS"]
puts "::error #{message_full}" if ENV["GITHUB_ACTIONS"]
```

Missing the second set of colons will prevent GitHub Actions from properly parsing these annotations, resulting in warnings and errors not being prominently displayed in the workflow run interface. This makes CI/CD issues harder to identify and debug.

---

## Use constraining types

<!-- source: alacritty/alacritty | topic: API | language: Rust | updated: 2024-03-07 -->

API functions should use specific types and enums to clearly communicate valid parameter values rather than accepting arbitrary generic types that suggest any value is acceptable.

When designing function signatures, avoid generic types like `&[u8]`, primitive types, or overly broad parameters when the function only accepts a limited set of valid inputs. Instead, use enums, specific types from relevant libraries, or custom types that encode the constraints directly in the type system.

For example, instead of accepting arbitrary parameters that appear to allow any value:
```rust
// Poor API design - suggests any parameters are valid
fn should_build_esc_key_sequence(
    key: &KeyEvent,
    text: &str,
    mode: TermMode,
    mods: ModifiersState,
) -> bool {
    // Implementation suggests only specific combinations are valid
}
```

Use types that make the valid parameter space explicit:
```rust
// Better API design - constraints are clear from types
enum KeySequenceMode {
    ReportAllKeys,
    DisambiguateEscCodes,
    Standard,
}

fn should_build_esc_key_sequence(
    key: &KeyEvent,
    mode: KeySequenceMode,
) -> bool {
    // Valid inputs are now clear from the signature
}
```

Similarly, prefer specific types from APIs over generic alternatives. Use `LPDWORD` from Windows APIs instead of `*mut u32` when available, or the actual type names rather than generic byte arrays when the function expects specific message formats.

This approach prevents incorrect usage, makes the API self-documenting, and catches invalid parameters at compile time rather than runtime.

---

## cross-platform API consistency

<!-- source: evanw/esbuild | topic: API | language: TypeScript | updated: 2024-03-07 -->

Design APIs to provide consistent behavior and user experience across different runtime environments and module systems. Abstract platform-specific differences behind a uniform interface so users don't need to handle environment-specific logic.

When designing APIs that run on multiple platforms (Node.js, Deno, browsers), ensure that:
- Core functionality works the same way regardless of the underlying platform
- Platform-specific optimizations (like `process.unref()` in Node vs Deno) are handled internally
- Export formats support both ESM and CommonJS consumption patterns
- Users can write the same code regardless of their target environment

For example, instead of requiring users to call different cleanup methods per platform:
```typescript
// Bad: Platform-specific API
if (isDeno) {
  await esbuild.stop(); // Required in Deno
} else {
  // Node handles cleanup automatically
}

// Good: Consistent API
await esbuild.stop(); // Works the same everywhere, with internal platform handling
```

This approach reduces cognitive load for API consumers and prevents environment-specific bugs in user code.

---

## Precise documentation language

<!-- source: hyprwm/Hyprland | topic: Documentation | language: Markdown | updated: 2024-03-02 -->

Documentation language should be precise, unambiguous, and clearly scoped to prevent misinterpretation while maintaining readability. Avoid open-ended terms that could be misunderstood or exploited, and use established terminology when dealing with legal, technical, or domain-specific concepts.

When writing documentation:
- Use precise, established terminology rather than vague language (e.g., "protected traits" instead of open-ended "traits")
- Clearly define scope and boundaries (e.g., "enforced by members of the hyprwm GitHub organization" rather than ambiguous "members")
- Remove unnecessary qualifiers that might create confusion (e.g., "harassment is unwelcome regardless of motivation" rather than "harassment about protected traits")
- Balance comprehensiveness with readability - include specific examples but use "including but not limited to" to indicate non-exhaustive lists

Example from legal documentation:
```
// Ambiguous - could be misinterpreted
"license does not hinder the ability of one to contribute to, or view the source code"

// Precise - clearly scoped
"license does not hinder the ability of any non-commercial entity to contribute to, redistribute or view the source code of the project"
```

This approach ensures documentation serves its intended purpose without creating loopholes or confusion for readers.

---

## Document configuration clearly

<!-- source: python-poetry/poetry | topic: Configurations | language: Yaml | updated: 2024-02-29 -->

Configuration files, hooks, and settings should include clear, accurate descriptions that explain their purpose and behavior. Descriptions should match the actual functionality and help developers understand what the configuration does and why it exists.

This prevents confusion when developers encounter unfamiliar configurations and reduces the cognitive load of understanding complex setups. Descriptions should be specific enough to distinguish between similar configurations and avoid misleading developers about the actual behavior.

Example of good configuration documentation:
```yaml
- id: poetry-lock-check
  name: poetry-lock-check
  description: check that poetry lock file is consistent with pyproject.toml
  
# Cron schedule with clear explanation
on:
  schedule:
    - cron: '0 * * * *'  # Run every hour at minute 0
```

Avoid vague descriptions that don't match the actual behavior, such as describing a hook as "synchronize dependencies" when it actually runs `poetry install --sync` by default, which may not be what users expect from a basic "install" operation.

---

## Add screenshot coverage

<!-- source: mermaid-js/mermaid | topic: Testing | language: Html | updated: 2024-02-28 -->

When adding a new rendering demo or introducing a new configuration/YAML option, always update the relevant Cypress integration/screenshot tests so the feature is exercised and captured automatically.

How to apply:
- Find the closest existing rendering/screenshot spec for the feature (e.g., the flowchart v2 rendering spec).
- Add a new `it(...)` case (or extend an existing one) that uses a snapshot helper to render the diagram source plus the exact config/front-matter that the demo uses.
- Ensure the test covers the new behavior/input (e.g., spacing options like `nodeSpacing`/`rankSpacing`, or new YAML config fields like `themeVariables`).

Example pattern (Cypress + snapshot):
```ts
it('Should render subgraphs with different nodeSpacing', () => {
  imgSnapshotTest(`---
title: Subgraph nodeSpacing and rankSpacing example
---
flowchart LR
  X --> Y
  subgraph X
    direction LR
    A
    C
  end
  subgraph Y
    direction LR
    B
    D
  end
`, {
    flowchart: { nodeSpacing: 1, rankSpacing: 1 },
  });
});

// And for new YAML config options:
imgSnapshotTest(`---
config:
  theme: base
  themeVariables:
    lineColor: yellow
---
flowchart LR
subgraph red
A --> B
end
`, {});
```
This keeps automated visual/regression coverage aligned with every user-visible change and every supported config surface.

---

## Configure HTTP requests properly

<!-- source: python-poetry/poetry | topic: Networking | language: Python | updated: 2024-02-26 -->

When making HTTP requests, use standard library enums for status codes, set appropriate timeouts, and handle redirects efficiently. Avoid raw status code numbers in favor of HTTPStatus enums for better readability and maintainability. Always configure timeouts to prevent indefinite hanging, preferably making them configurable via environment variables with sensible defaults. For upload operations, consider using HEAD requests to check for redirects before expensive POST operations to avoid retransmitting large payloads.

Example:
```python
from http import HTTPStatus
import os

# Use HTTPStatus enums instead of raw codes
if resp.status_code in (HTTPStatus.MOVED_PERMANENTLY, HTTPStatus.PERMANENT_REDIRECT):
    # handle redirect

# Configure timeouts with environment variable support
timeout = int(os.getenv('POETRY_REQUEST_TIMEOUT', 60))
response = session.get(url, timeout=timeout)

# Check for redirects before expensive operations
resp = session.head(url)
if resp.status_code == HTTPStatus.MOVED_PERMANENTLY:
    url = resp.headers['Location']
```

---

## Cache expensive computations

<!-- source: python-poetry/poetry | topic: Performance Optimization | language: Python | updated: 2024-02-25 -->

Identify expensive operations that may be called multiple times and implement appropriate caching mechanisms to avoid redundant computation. Use `@cached_property` for class properties that involve expensive calculations, store expensive method calls in local variables when used repeatedly in loops, and consider memoization for frequently accessed data that doesn't change during execution.

Examples of expensive operations to cache:
- File I/O operations like reading configuration files
- Property calculations that iterate over collections
- System information gathering
- Method calls inside loops that return the same result

```python
# Instead of recalculating expensive properties in loops:
for item in items:
    if self.option("top-level") and not any(
        locked.is_same_package_as(r) for r in root.all_requires
    ):
        # expensive calls repeated for each item

# Store expensive calculations outside the loop:
is_top_level = self.option("top-level")
all_requires = root.all_requires
for item in items:
    if is_top_level and not any(
        locked.is_same_package_as(r) for r in all_requires
    ):
        # cached values used efficiently

# Use @cached_property for expensive file operations:
@cached_property
def includes_system_site_packages(self) -> bool:
    pyvenv_cfg = self._path / "pyvenv.cfg"
    return "include-system-site-packages = true" in pyvenv_cfg.read_text()
```

This optimization prevents redundant work and can significantly improve performance, especially in loops or frequently called code paths.

---

## consistent error handling

<!-- source: alacritty/alacritty | topic: Error Handling | language: Rust | updated: 2024-02-23 -->

Maintain uniform error handling patterns throughout the codebase. Avoid mixing different error handling approaches like panics, process::exit(), and proper Result returns within the same application flow.

When functions can fail, consistently use Result types and propagate errors up the call stack rather than handling them inconsistently at different levels. This makes error handling predictable and allows callers to decide how to respond to failures.

Example of inconsistent handling to avoid:
```rust
// Bad: mixing panic and proper error handling
pub fn migrate(options: MigrateOptions) {
    if let Err(e) = some_operation() {
        eprintln!("Error: {}", e);
        process::exit(1);  // Inconsistent with other subcommands
    }
}

// Good: consistent Result-based error handling
pub fn migrate(options: MigrateOptions) -> Result<(), Box<dyn Error>> {
    some_operation()?;  // Propagate errors consistently
    Ok(())
}
```

Instead of using panics for error conditions, return proper error types with span information when possible. This is especially important for compile-time errors and user-facing operations where graceful degradation is preferred over abrupt termination.

The goal is to make error handling predictable across the entire codebase, allowing for better testing, debugging, and user experience.

---

## hide implementation details

<!-- source: helix-editor/helix | topic: API | language: Rust | updated: 2024-02-20 -->

When designing APIs, avoid exposing internal structures, implementation details, or platform-specific concepts to external consumers. Instead, create clean, stable interfaces that focus on what users need to accomplish rather than how the system works internally.

This principle helps maintain API stability, reduces coupling, and makes the interface easier to understand and use. Internal details like context objects, editor structs, document IDs, or event types should be abstracted away behind purpose-built API methods.

For example, instead of exposing editor and context structs directly:

```rust
// Bad - exposes implementation details
module.register_fn("editor-cursor", Editor::cursor);
module.register_fn("cx->cursor", |cx: &mut Context| cx.editor.cursor());

// Good - provides clean, purpose-built interface  
module.register_fn("active-cursor", get_active_cursor);
```

Similarly, avoid exposing internal IDs or enum variants that are meant for internal use:

```rust
// Bad - exposes document ID creation and internal types
module.register_fn("doc-id->usize", document_id_to_usize);
module.register_value("PromptEvent::Update", PromptEvent::Update);

// Good - use opaque types or only expose what's needed
// Document IDs should be opaque handles, Update events shouldn't be exposed to plugins
```

The goal is to design APIs from the perspective of "What should users be able to do?" rather than "What does our internal implementation look like?" This creates more maintainable, stable, and user-friendly interfaces.

---

## use strong keys

<!-- source: wavetermdev/waveterm | topic: Security | language: Go | updated: 2024-02-14 -->

Always use secure cryptographic algorithms and minimum key sizes—even for dummy, test, or helper keys. Avoid generating or shipping 1024-bit RSA keys (they are considered weak). Prefer modern algorithms (ed25519) when supported; otherwise use at least 2048-bit RSA. Mark any ephemeral/dummy keys clearly in code, avoid persisting them, and follow library defaults where possible.

How to apply:
- Prefer ed25519 for SSH signers when the library supports it (smaller, faster, and stronger):
  pub, priv, _ := ed25519.GenerateKey(rand.Reader)
  signer, _ := ssh.NewSignerFromKey(priv)
- If RSA is required, use >=2048 bits (2048 is minimum; 3072+ for higher security):
  // bad: rsa.GenerateKey(rand.Reader, 1024)
  // good:
  key, err := rsa.GenerateKey(rand.Reader, 2048)
  signer, err := ssh.NewSignerFromKey(key)

Additional guidance:
- Do not hard-code weak sizes; use named constants (e.g., RSA2048 = 2048) so they can be audited and updated.
- Keep dummy keys ephemeral (in-memory only) and document why they exist to avoid accidental reuse.
- Prefer library-supplied secure defaults and review cryptographic code during security reviews.

Motivation: Weak keys reduce the security of authentication and can introduce vulnerabilities even in helper code. Using strong defaults prevents accidental weakening of systems and aligns code with current security best practices.

---

## Prefer streaming operations

<!-- source: wavetermdev/waveterm | topic: Performance Optimization | language: TypeScript | updated: 2024-02-09 -->

Motivation: avoid large, unnecessary memory allocations and excessive decoding or retention of full data sets. For parsing, logs, or history, operate on raw bytes or streams and read only the portion you need. For long-lived state, avoid keeping full large objects in memory—cap, page, or store lightweight references.

How to apply:
- Parse bytes, not decoded strings: work with Uint8Array slices and byte indexes so you only allocate what's needed and delay TextDecoder until you must produce text.
  Example (from change in discussion):
  let curLineBytes = new Uint8Array(this.rawData.buffer, this.parsePos, i - this.parsePos);
  let jsonStartIndex = curLineBytes.indexOf("{".charCodeAt(0));
  let byteSize = curLineBytes.slice(jsonStartIndex, curLineBytes.length).length;
  // only decode when needed: new TextDecoder().decode(curLineBytes.slice(jsonStartIndex))

- For large files (logs), do not read the entire file into memory. Use streaming APIs, read-from-end buffered seeks, or delegate to existing OS tools such as `tail -n` and capture output. If implementing in-process, read the file in chunks from the end until you have enough lines rather than reading the whole file.

- Manage in-memory history/state: avoid unbounded retention of large generated content. Options include capping history size, storing compact metadata or references, lazy-loading full content, or persisting to disk/DB and fetching on demand.

Why this improves performance: reduces peak memory usage, lowers GC pressure, and often speeds up operations by avoiding expensive encodings and unnecessary data copies. Follow this rule when designing parsers, log readers, and history/state storage to prevent scalability bottlenecks.

---

## Propagate errors clearly

<!-- source: wavetermdev/waveterm | topic: Error Handling | language: Go | updated: 2024-02-07 -->

Always return and propagate errors; surface them to callers and the UI, and clean up resources on error paths.

Motivation
- Avoid hiding failures by logging only or encoding errors as special string values. Returning errors lets callers decide how to handle, retry, or present failures. Ensure resources (files, network streams, conex) are closed with defer immediately after successful acquisition so early returns and panics don't leak resources.

Rules
- Use idiomatic error returns (value, error). Do not encode errors as sentinel strings in normal return values.
  Example: change parseCopyFileParam(info string) from returning remote=="error" to:
    func parseCopyFileParam(info string) (remote string, path string, err error) {
        if bad { return "", "", fmt.Errorf("bad param: %s", info) }
        return remoteName, path, nil
    }
- Propagate errors upward. Library/logic functions should return errors instead of only logging. Let callers convert errors to user-facing protocol/state or retry.
  Example: instead of log.Printf("Open AI Update packet err: %v"), return the error and let the caller attach it to an update packet or decide recovery.
- Surface errors to the client/UI via explicit fields in protocol/state structures rather than relying on server logs.
  Example: add an Error string (or typed error info) to chat message structs so stream code can send intermediate error messages to the client.
    message := &packet.OpenAICmdInfoChatMessage{Error: err.Error(), MessageID: id}
- Clean up resources on all code paths. After acquiring a resource (file, connection, iterator), call defer Close() immediately.
  Example:
    f, err := os.Open(path)
    if err != nil {
        return err
    }
    defer f.Close()
- Handle errors in loops and streaming paths: when encountering I/O or protocol errors, return or convert the error into a protocol-level update so the UI can display it; avoid silently returning after a log.Printf.

When to log vs return
- Log at top-level handlers where you have context to decide user-visible behavior. Lower-level functions should return errors. Only use log.Printf for unexpected conditions that will be returned/handled at a higher level.

Benefits
- Makes failure handling predictable and testable.
- Enables clients to present useful error information instead of missing failures.
- Prevents resource leaks on error paths.

References: discussions 0, 1, 2, 3.

---

## centralize sentinel names

<!-- source: wavetermdev/waveterm | topic: Naming Conventions | language: Go | updated: 2024-02-07 -->

Define and use named constants for special sentinel identifiers (e.g., "local", "connected") and add semantic methods on domain types near their definitions to encapsulate boolean checks (e.g., RemoteType.IsLocal()). Motivation: magic strings and scattered boolean logic reduce clarity and increase risk of inconsistent checks. Placing constants and small predicates next to the type that owns the concept creates a single source of truth and improves identifier semantics.

How to apply:
- Replace literal sentinel strings with package-scoped constants with clear names. Put them in a file close to related resolver/constants (or the type they relate to). Example:
  // in resolver.go (or near R_Remote definitions)
  const (
      SentinelLocal     = "local"
      SentinelConnected = "connected"
  )
  // Use SentinelLocal instead of "local" throughout code.

- Add semantic helper methods on the domain type that perform common checks instead of repeating boolean expressions. Place these methods beside the type declaration (e.g., sstore.go next to RemoteType):
  func (r RemoteType) IsLocal() bool {
      // encapsulate the precise logic once
      return r.Local && !r.IsSudo()
  }

- Use the constants and helpers where previously ad-hoc logic occurred. Example replacement from discussion:
  // before: if ids.Remote.DisplayName == "local" { ... }
  // after:
  if ids.Remote.DisplayName == SentinelLocal || ids.Remote.IsLocal() {
      // consistent handling for local remote
  }

Rules summary:
- Never scatter sentinel string literals across code; declare named constants.
- Place constants near related resolver/type definitions for discoverability.
- Encapsulate repeated boolean checks in clearly named methods on the owning type (IsLocal, IsSudo, etc.).
- Prefer calling the helper methods (r.IsLocal()) rather than repeating the boolean expression.

Benefits: improves readability, ensures consistency, reduces bugs from divergent checks, and makes future changes (e.g., renaming sentinel values or changing local-ness rules) much simpler.

---

## targeted CSS modifications

<!-- source: prettier/prettier | topic: Code Style | language: Css | updated: 2024-02-03 -->

Make targeted, purposeful CSS modifications that either enhance visual presentation or fix specific functionality issues without disrupting existing styles. When adding new styles, focus on specific improvements like centering text or adjusting colors. When modifying existing styles, preserve the original intent and make minimal changes to address the specific problem.

For example, instead of changing existing padding values, adjust positioning properties to fix overlapping issues:

```css
/* Good: Targeted addition for visual improvement */
.sponsorsSection h2 {
  text-align: center;
}

/* Good: Minimal adjustment to fix functionality */
.button {
  top: -5px; 
  right: 16px;
}
```

This approach maintains code stability while allowing for necessary improvements and fixes.

---

## Config schema defaults

<!-- source: mermaid-js/mermaid | topic: Configurations | language: Yaml | updated: 2024-02-01 -->

When updating configuration schemas, ensure each config option is fully specified and not redundantly redefined.

Apply these rules:
1) **Always set `type` and `default` for new properties** so downstream consumers get predictable behavior and the schema remains type-correct.
2) **Use inheritance from base config definitions** (`$defs` / `allOf`) and **remove redundant properties** that are already provided by the base schema—only override when behavior truly differs.
3) **Keep `default` consistent with the declared `type`** and (when you’re standardizing UX) align defaults across related diagram configs.

Example (pattern):
```yaml
properties:
  markdownAutoWrap:
    type: boolean
    default: true

BlockDiagramConfig:
  title: Block Diagram Config
  allOf: [{ $ref: '#/$defs/BaseDiagramConfig' }]
  description: The object containing configurations specific for block diagrams.
  type: object
  unevaluatedProperties: false
  properties:
    padding:
      type: number
      default: 8
# Note: don’t re-declare useMaxWidth here if BaseDiagramConfig already defines it with the desired default.
```

---

## Secure API URL parsing

<!-- source: Homebrew/brew | topic: API | language: Shell | updated: 2024-01-14 -->

When parsing API endpoint URLs, implement rigorous input validation using precise regular expressions. This includes:
- Escaping special characters in domain literals (e.g., `github\.com`)
- Excluding URL separators (like /, ?, #) from username/password patterns
- Restricting allowed characters for security-sensitive components like API keys
- Minimizing unnecessary capture groups to improve clarity and performance

For example, instead of:
```bash
[[ "${API_URL}" =~ https://(([^:@]+)(:([^@]+))?@)?github.com/(.*)$ ]]
```

Use a more precise pattern:
```bash
[[ "${API_URL}" =~ https://(([^:@/?#]+)(:([^@/?#]+))?@)?github\.com/(.*)$ ]]
```

For API keys or tokens, consider restricting to known valid formats:
```bash
[[ "${API_TOKEN}" =~ ^[[:alnum:]_]+$ ]]
```

This approach prevents security vulnerabilities and ensures consistent API authentication handling across your application.

---

## Use example configuration files

<!-- source: prettier/prettier | topic: Configurations | language: Json | updated: 2024-01-08 -->

When providing team configuration files that developers might want to customize, use `.example` suffixes and implement automatic copying mechanisms to avoid conflicts with personal settings.

This approach prevents team configuration files from overriding individual developer preferences while ensuring new team members get sensible defaults. The pattern works by:

1. Committing configuration files with `.example` extensions (e.g., `settings.example.json`)
2. Adding the actual config file to `.gitignore` 
3. Implementing automatic copying via package scripts when the target file doesn't exist

Example implementation:
```json
// package.json
{
  "scripts": {
    "postinstall": "node -e \"try{fs.existsSync('.vscode/settings.json')||fs.writeFileSync('.vscode/settings.json',fs.readFileSync('.vscode/settings.example.json'))}catch(_){}\""
  }
}
```

This pattern is particularly valuable for IDE settings, environment configurations, and any config files that developers commonly customize. It balances team consistency with individual developer workflow preferences.

---

## specify tool version requirements

<!-- source: python-poetry/poetry | topic: CI/CD | language: Markdown | updated: 2024-01-05 -->

When documenting CI/CD tools and integrations, always specify exact version requirements and compatibility constraints. This prevents integration failures and ensures reproducible builds across different environments.

Include specific version numbers using comparison operators (>=, >, ==) rather than vague statements like "recent versions" or "supported versions". When possible, provide fallback instructions or alternative configurations for older versions that teams might still be using.

Example:
```markdown
**Yes**. Provided that you are using `tox` >= 4, you can use it in combination with
the PEP 517 compliant build system provided by Poetry. (With tox 3, you have to set the 
[isolated build](https://tox.wiki/en/3.27.1/config.html#conf-isolated_build) option.)
```

This approach helps teams understand exactly what they need to install or upgrade, and provides clear migration paths when updating their CI/CD pipelines.

---

## Use environment-aware configurations

<!-- source: vercel/turborepo | topic: Configurations | language: JavaScript | updated: 2023-12-26 -->

Configure paths and system references dynamically to ensure they work across all environments (development, testing, production). Avoid hardcoded paths or environment-specific values that will break when code is packaged or deployed.

For file paths:
```javascript
// Avoid this:
const filePath = "../../../../../examples/basic/README.md";

// Use this instead:
const rootReadme = path.join(prompts.root, "README.md");
// Or with @turbo/workspaces:
const rootReadme = path.join(project.paths.root, "README.md");
```

For tool-specific code:
```javascript
// Avoid hardcoding for specific package managers:
data = data.replace(/\bpnpm\b/g, `${selectedPackageManager} run`);

// Make it work for all package managers:
// Transform from any package manager to the selected one
```

This approach ensures configurations remain portable across different environments and development setups, preventing unexpected failures during deployment or when sharing code with other team members.

---

## centralize configuration values

<!-- source: wavetermdev/waveterm | topic: Configurations | language: TSX | updated: 2023-12-15 -->

Keep layout constants, feature flags, and user-configurable settings in centralized configuration modules (not hardcoded in components). Motivation: makes it easy to find and change UI "magic" values (e.g., tab width, spacing) and ensures behavior can be toggled per-environment or per-user (e.g., suppressing update banners when users turn off update checks).

How to apply:
- Create dedicated config files (examples: magiclayout.ts, featureflags.ts, clientConfig.ts) and export named values.
- Import those values in components instead of declaring local constants or conditionals.
- Respect user settings and feature flags when rendering UI; surface updates only via agreed channels if the corresponding setting is disabled.

Examples:
- Move tab width into magiclayout.ts:
  // magiclayout.ts
  export const TAB_WIDTH = 175;

  // tabs.tsx
  import { TAB_WIDTH } from '../../config/magiclayout';

- Check a user setting before showing an update sidebar entry:
  // clientConfig.ts (runtime/user settings)
  export const clientConfig = {
    checkForUpdates: true, // toggled by user
  };

  // sidebar.tsx
  import { clientConfig } from '../../config/clientConfig';
  ...
  {clientConfig.checkForUpdates && clientData?.releaseinfo?.releaseavailable && (
    <If condition>
      ...update banner...
    </If>
  )}

Notes:
- Keep config modules focused and discoverable (group layout constants together, feature flags together).
- Allow environment/user overrides (env vars, persisted settings) and document intent so components remain declarative and testable.

---

## Document CI workflow rationale

<!-- source: prettier/prettier | topic: CI/CD | language: Yaml | updated: 2023-12-11 -->

Always include clear comments explaining the reasoning behind CI workflow decisions, including test environment separation, version matrix choices, and build requirements. This prevents confusion about when different workflows should be used and helps maintain consistency across the team.

For test workflows, clearly distinguish between development tests (fast, no build required) and production tests (with build artifacts). For version matrices, document the purpose of each version selection:

```yaml
node:
  # Latest even version
  - "20"
  # Minimal version for development  
  - "16"
include:
  - os: "ubuntu-latest"
    # Pick a version that is fast (normally highest LTS version)
    node: "18"
    ENABLE_CODE_COVERAGE: true
```

This documentation helps developers understand which workflow to modify for different types of changes and prevents misplacement of build-dependent steps in development test workflows.

---

## Add explanatory comments

<!-- source: prettier/prettier | topic: Documentation | language: JavaScript | updated: 2023-11-10 -->

Add explanatory comments for complex logic, special cases, or non-obvious code behavior. Comments should explain the "why" behind the code and "what" specific conditions or syntax patterns are being handled.

When code involves:
- Complex conditional logic or pattern matching
- Special handling for edge cases
- Non-obvious business rules or technical requirements
- Code that exists for specific external compatibility reasons

Include comments that:
- Explain the purpose and reasoning
- Provide concrete examples when helpful
- Reference external documentation or issues when relevant

Example from the discussions:
```javascript
// Prettier does not officially support stylus.
// But, we need to handle "stylus" here for printing a style block in Vue SFC as stylus code by external plugin.
// https://github.com/prettier/prettier/pull/12707
if (lang === "stylus") {
  return inferParserByLanguage("stylus", options);
}
```

Or for complex conditions:
```javascript
// For example, there is the following key-value pair:
//   "xs-only": "only screen and (max-width: #{map-get($grid-breakpoints, "sm")-1})"
// "only screen and (max-width: #{map-get($grid-breakpoints, " is a "value-string"
// and "sm" is a "value-word"
// We should not insert any spaces and lines here.
if (isMapItemNode) {
  const isPartOfValue = node.groups?.[1]?.type === "value-colon" && i > 1;
  // ...
}
```

Avoid over-commenting simple or self-explanatory code, but err on the side of clarity for complex logic that future maintainers will need to understand.

---

## Consistent naming conventions

<!-- source: alacritty/alacritty | topic: Naming Conventions | language: Other | updated: 2023-10-30 -->

Maintain consistent naming patterns and capitalization throughout the codebase, especially for configuration options, string values, and identifiers. This includes using consistent capitalization for similar values (e.g., "None" instead of mixing "none" and "None"), adopting uniform naming patterns for related options (e.g., using "duration" consistently instead of verbose alternatives like "fade_time_in_secs"), and ensuring clear, consistent prefixes or patterns for grouped identifiers.

For example, instead of mixing capitalization:
```
# Inconsistent
*line_indicator* { foreground = "none", background = "none" }
*decorations* "Full" | "None" | "Transparent"

# Consistent  
*line_indicator* { foreground = "None", background = "None" }
*decorations* "Full" | "None" | "Transparent"
```

Similarly, prefer concise, consistent naming over verbose alternatives:
```
# Verbose and inconsistent
*fade_time_in_secs* <float>

# Concise and consistent with other duration options
*duration* <integer>
```

This approach reduces cognitive load, prevents confusion, and makes the codebase more maintainable by establishing predictable naming patterns that developers can rely on.

---

## Assess security trade-offs

<!-- source: alacritty/alacritty | topic: Security | language: Other | updated: 2023-10-08 -->

When introducing dependencies or features that have security implications, explicitly evaluate whether the benefits justify the potential risks. Prefer safer alternatives when available, and clearly document security considerations.

For dependencies, favor native implementations over transpiled code from memory-unsafe languages. For example, choose a "small safe rust parser" over a "massive transpilation of a C library" that could introduce security vulnerabilities.

For features that access system resources (like clipboard, filesystem, network), be explicit about potential abuse scenarios in documentation. Instead of downplaying risks with phrases like "not that necessary," clearly state that "allowing any application to read from the clipboard can be easily abused while not providing significant benefits."

Always consider: Does this dependency/feature introduce unnecessary attack surface? Are there safer alternatives? Have we clearly communicated the security implications to users?

---

## unsafe code practices

<!-- source: alacritty/alacritty | topic: Security | language: Rust | updated: 2023-10-03 -->

Ensure proper use and documentation of unsafe code to prevent security vulnerabilities. The `unsafe` keyword should only be used for operations that can violate memory safety contracts, not for general thread safety or global state concerns. All unsafe functions must include comprehensive safety documentation explaining the contracts that callers must uphold.

When marking code as unsafe:
- Only use `unsafe` for true memory safety violations (e.g., raw pointer dereferencing, FFI calls)
- Do NOT use `unsafe` for thread safety issues or global state mutations that use safe Rust APIs
- Always document safety requirements with `/// # Safety` comments

Example of proper unsafe documentation:
```rust
/// # Safety
///
/// The underlying sources must outlive their registration in the `Poller`.
unsafe fn register(&mut self, poller: &Arc<Poller>, event: Event, mode: PollMode) -> io::Result<()>;
```

Example of improper unsafe usage:
```rust
// WRONG: This just calls std::env::remove_var, which is safe
unsafe fn reset_activation_token_env() {
    std::env::remove_var("DESKTOP_STARTUP_ID");
}
```

Thread safety and global state concerns should be addressed through proper synchronization primitives (Mutex, RwLock) rather than marking functions as unsafe.

---

## Verify optional chaining necessity

<!-- source: prettier/prettier | topic: Null Handling | language: JavaScript | updated: 2023-09-18 -->

Analyze whether optional chaining (`?.`) is actually needed based on the surrounding context and prior validations. Remove optional chaining when values are already confirmed to be truthy through previous checks, but add it when there's genuine risk of null/undefined access.

**Remove when redundant:**
```javascript
// Bad: unnecessary after null check
if (!adjacentNodes.previous || !adjacentNodes.next) {
  return true;
}
const previousKind = adjacentNodes.previous?.kind; // redundant ?. 
const nextKind = adjacentNodes.next?.kind; // redundant ?.

// Good: direct access after validation
if (!adjacentNodes.previous || !adjacentNodes.next) {
  return true;
}
const previousKind = adjacentNodes.previous.kind;
const nextKind = adjacentNodes.next.kind;
```

**Add when necessary:**
```javascript
// Bad: potential exception
return node.groups[0].value === "url";

// Good: safe access
return node.groups?.[0].value === "url";
```

Before using optional chaining, verify: 1) Is there a genuine possibility the value could be null/undefined? 2) Have you already validated the value exists in prior code? 3) Are you mimicking existing safe patterns in the codebase? This prevents both unnecessary defensive coding and potential runtime exceptions.

---

## strip event parameters

<!-- source: electron/electron | topic: Security | language: JavaScript | updated: 2023-08-28 -->

When exposing IPC event handlers through contextBridge in Electron applications, always strip the event parameter before calling renderer callbacks to prevent security vulnerabilities. The event object contains `event.sender` which can be exploited by malicious code in the renderer process to send arbitrary IPC messages, leading to privilege escalation.

Instead of directly passing the callback:
```js
onWindowFocus: (callback) => ipcRenderer.on('window-focus', callback)
```

Strip the event parameter by wrapping the callback:
```js
onWindowFocus: (callback) => ipcRenderer.on('window-focus', () => callback())
```

This security practice prevents the renderer process from accessing the event object and its potentially dangerous properties, maintaining proper isolation between the main and renderer processes.

---

## optimize data structure operations

<!-- source: neovim/neovim | topic: Algorithms | language: C | updated: 2023-07-29 -->

When working with data structures, prioritize efficiency through proper memory management and compact data representation. Use appropriate conversion patterns that handle memory cleanup correctly, and leverage bit manipulation techniques for space-efficient data storage.

For data structure conversions, ensure proper memory management by clearing source data after copying:
```c
typval_T rv = {
  .vval.v_list = fr_list,
  .v_type = VAR_LIST
};
Object result = vim_to_object(&rv);
tv_clear(&rv);  // Clean up source after conversion
return result;
```

For compact data representation, use bitmasks and enums instead of multiple boolean flags:
```c
enum {
  kCapsLock = 0x02,
  kNumLock = 0x10,
};

// Instead of multiple #ifdef blocks, use:
if (mods & kCapsLock) {
  PUT(*dict, "CapsLock", BOOLEAN_OBJ(true));
}
```

This approach reduces memory overhead, improves cache locality, and makes the code more maintainable while avoiding platform-specific conditional compilation complexity.

---

## Document public API elements

<!-- source: octokit/octokit.net | topic: Documentation | language: C# | updated: 2023-07-24 -->

Every public API element (classes, methods, properties, constructors) must have XML documentation comments that clearly describe its purpose and usage. This improves developer experience through IntelliSense and ensures the API is well-documented.

For implementation classes that implement interfaces:
- Use `<inheritdoc />` at the class level to inherit documentation from interfaces
- Don't duplicate documentation in both places to avoid maintenance issues

For method parameters and properties:
- Place important contextual information in `<param>` descriptions rather than `<remarks>` for better IntelliSense visibility
- Use the format: `<param name="paramName">Description (additional context)</param>`

Example:
```csharp
/// <summary>
/// Creates a new repository transfer description.
/// </summary>
/// <param name="newOwner">The new owner of the repository after the transfer.</param>
/// <param name="teamId">A list of team Ids to add to the repository (only applies to Organization owned repositories).</param>
public RepositoryTransfer(string newOwner, IReadOnlyList<int> teamId)
{
    Ensure.ArgumentNotNullOrEmptyString(newOwner, nameof(newOwner));
    Ensure.ArgumentNotNullOrEmptyEnumerable(teamId, nameof(teamId));
    
    NewOwner = newOwner;
    TeamId = teamId;
}
```

Maintain consistency across similar members - if one method overload has documentation, all overloads should be documented with the same level of detail.

---

## Follow configuration conventions

<!-- source: evanw/esbuild | topic: Configurations | language: TypeScript | updated: 2023-07-13 -->

When working with configurations, maintain consistency by following established conventions and proper categorization. This includes using naming patterns that match related tools/frameworks and organizing configuration entries in appropriate sections based on actual capabilities.

For naming conventions, prefer established patterns from related ecosystems:
```typescript
// Good: matches Webpack convention
sideEffects: false

// Avoid: creates new naming pattern
sideEffectFree: true
```

For configuration organization, ensure entries are categorized correctly based on actual support:
```typescript
// Good: placed in appropriate section
const unsupportedPlatforms = {
  'aarch64-linux-android': '@esbuild/android-arm64',
}

// Avoid: miscategorized based on assumptions
const supportedPlatforms = {
  'aarch64-linux-android': '@esbuild/android-arm64', // Not actually supported
}
```

This approach makes configurations more intuitive for users familiar with related tools and prevents confusion about actual capabilities.

---

## Context-aware module loading

<!-- source: electron/electron | topic: Configurations | language: TypeScript | updated: 2023-06-13 -->

Choose appropriate module loading syntax based on your execution context and build configuration settings. Different environments have different module system capabilities that must be respected.

When `tsconfig.json` has `module: esnext` or `package.json` has `type: module`, import statements may not be automatically transformed to require calls. In contexts like sandboxed preload scripts that don't support ESM, you must use require syntax instead:

```typescript
// In sandboxed preload scripts, use require even with ESM config
const { ipcRenderer, contextBridge } = require('electron/renderer');

// For dynamic imports in ESM contexts, use import()
packageJson = await import(packageJsonPath, { assert: { type: 'json' } });
```

Always verify that your chosen loading mechanism is compatible with both your build configuration and the target execution environment. Sandboxed contexts, Node.js versions, and TypeScript compiler settings all influence which module syntax will work correctly.

---

## Remove internal APIs

<!-- source: electron/electron | topic: Security | language: TypeScript | updated: 2023-06-13 -->

Delete internal system properties and APIs after use to prevent application code from accessing protected functionality. This security practice ensures that internal methods cannot be called by user code, protecting system integrity and preventing potential security vulnerabilities.

When internal properties are exposed temporarily (e.g., during initialization), clean them up immediately after use:

```typescript
const { appCodeLoaded } = process;
delete process.appCodeLoaded;
```

This pattern prevents application code from discovering and potentially misusing internal system APIs that should remain private to the framework or runtime environment.

---

## Environment variable handling

<!-- source: cypress-io/cypress | topic: Configurations | language: JavaScript | updated: 2023-05-24 -->

Environment variables should be properly validated, parsed, and documented with clear override mechanisms. Always validate that environment variable names are non-empty strings before processing. When parsing environment variable values, trim whitespace and remove surrounding quotes to handle cross-platform differences, especially on Windows where quotes may be preserved. Provide meaningful override mechanisms using descriptive environment variable names rather than hardcoding values.

Example of proper environment variable handling:
```javascript
function getEnv(varName, trim = false) {
  la(is.unemptyString(varName), 'expected environment variable name, not', varName)
  
  const envVar = process.env[varName]
  const configVar = process.env[`npm_config_${varName}`]
  
  let result = envVar || configVar
  
  // Handle Windows quote preservation and whitespace
  return trim ? dequote(_.trim(result)) : result
}

// Provide override mechanisms with descriptive names
if (process.env.CYPRESS_DOCKER_DEV_INSPECT_OVERRIDE) {
  argv.unshift(`--inspect-brk=${process.env.CYPRESS_DOCKER_DEV_INSPECT_OVERRIDE}`)
} else {
  argv.unshift('--inspect-brk=5566')
}

// Platform-specific environment setup
function getOpenModeEnv() {
  if (os.platform() !== 'linux') return
  
  // Document why this environment variable is needed
  return { GTK_USE_PORTAL: '1' }
}
```

This approach ensures configuration is flexible, well-documented, and handles cross-platform differences gracefully while providing clear override paths for different deployment scenarios.

---

## Choose familiar, intuitive names

<!-- source: alacritty/alacritty | topic: Naming Conventions | language: Yaml | updated: 2023-05-20 -->

When naming variables, methods, or configuration options, prioritize terms that are both intuitive to users and familiar within the relevant domain. Avoid technical jargon when simpler, more natural alternatives exist, while also preferring established terminology that the target audience already knows.

For user-facing actions, choose verbs that clearly communicate the intended behavior. For example, prefer "Create" over "Spawn" for window operations, as "create" is more natural and immediately understandable to users.

For domain-specific concepts, use well-established terminology that practitioners in that field would recognize. For instance, in terminal emulators, use "inverse" rather than "opposing" when referring to swapped foreground/background colors, since "inverse text" is the standard term.

Example:
```yaml
# Preferred - uses natural, domain-appropriate language
- CreateNewWindow    # intuitive action verb
- inverse_colors     # established terminal terminology

# Avoid - technical jargon or non-standard terms  
- SpawnNewWindow     # technical but less intuitive
- opposing_colors    # generic but not domain-standard
```

This approach ensures that names are both accessible to users and technically precise within the relevant context.

---

## Network request configuration

<!-- source: python-poetry/poetry | topic: Networking | language: Markdown | updated: 2023-05-14 -->

When implementing or documenting network functionality, ensure proper configuration options are provided and compatibility across different environments is considered. Network requests should have configurable timeouts and work reliably across platform variations.

For timeout configuration, document default values and provide environment variables for customization:
```bash
# Default timeout is 15 seconds, similar to pip
# Use POETRY_REQUESTS_TIMEOUT to customize
export POETRY_REQUESTS_TIMEOUT=30
```

For cross-platform network requests, include platform-specific parameters when necessary:
```powershell
# Windows PowerShell 5.1 compatibility
(Invoke-WebRequest -Uri https://example.com/script.py -UseBasicParsing).Content | python
```

This ensures network operations are both configurable for different use cases and compatible across the environments where users will actually run the code. Always test network functionality on the target platforms and document any platform-specific requirements or parameters needed for reliable operation.

---

## avoid redundant tool configuration

<!-- source: python-poetry/poetry | topic: Code Style | language: Toml | updated: 2023-04-30 -->

When configuring code style tools, avoid enabling rules or settings that duplicate functionality already provided by other tools in your toolchain. This reduces configuration complexity, prevents conflicting rules, and improves maintainability.

Before adding a new linting rule or formatter setting, verify that it doesn't overlap with existing tools:
- Don't enable `flake8-annotations` (ANN) when using mypy in strict mode
- Don't enable `flake8-quotes` (Q) when using black for formatting  
- Don't specify configuration values that match the tool's defaults

Example from pyproject.toml:
```toml
[tool.ruff]
extend-select = [
    "B",  # flake8-bugbear
    # "ANN",  # flake8-annotations - redundant with mypy strict mode
    "C4",  # flake8-comprehensions
    # "Q",  # flake8-quotes - black handles quote formatting
]

[tool.ruff.isort]
# section-order = [...] # unnecessary, matches default order
```

This approach ensures your style enforcement is consistent, avoids tool conflicts, and keeps configuration files focused on meaningful customizations rather than redundant specifications.

---

## Verify configuration options

<!-- source: python-poetry/poetry | topic: Configurations | language: Other | updated: 2023-04-07 -->

Always verify that configuration file options and command flags are correct and properly documented. Incorrect configuration syntax can cause silent failures or unintended side effects that are difficult to debug.

Common issues include:
- Using deprecated or non-existent configuration options that fail silently
- Using commands without appropriate flags that cause broader changes than intended

Before committing configuration changes:
1. Check official documentation for correct option names and syntax
2. Use specific flags to limit scope of operations (e.g., `poetry lock --no-update` instead of `poetry lock`)
3. Test configuration changes to ensure they work as expected

Example from the discussions:
```
# Wrong - silently breaks functionality
[flake8]
enable-select = TC, TC1

# Correct - properly documented option
[flake8] 
extend-select = TC, TC1
```

```bash
# Wrong - updates all dependencies unintentionally
poetry lock

# Correct - only regenerates lock without updating versions
poetry lock --no-update
```

---

## Thoughtful error handling

<!-- source: cypress-io/cypress | topic: Error Handling | language: JavaScript | updated: 2023-03-24 -->

Implement error handling that considers recoverability, appropriate logging levels, and prevents redundant operations. Use warnings for recoverable errors during retry attempts, and errors only for final failures. Avoid duplicate error logging when errors are already wrapped or handled elsewhere. Implement guards to prevent redundant error handler setup, and distinguish between recoverable errors (network issues, temporary failures) and non-recoverable ones (configuration errors) to avoid unnecessary retry loops.

Example of proper retry error handling:
```javascript
async function importWithRetry(importFn) {
  try {
    return await importFn()
  } catch (error) {
    for (let i = 0; i < 3; i++) {
      console.warn(`Retrying import attempt ${i + 1}/3: ${url?.href}`) // Warning, not error
      // ... retry logic
    }
    console.error(`Final import failure after retries: ${url?.href}`) // Error only on final failure
    throw error
  }
}
```

Avoid duplicate logging:
```javascript
// Instead of logging and throwing
errors.log(err)
throw err

// Just throw the wrapped error
throw errors.get('ERROR_WRITING_FILE', dest, error)
```

---

## Document non-obvious code

<!-- source: cypress-io/cypress | topic: Documentation | language: JavaScript | updated: 2023-03-24 -->

Add explanatory comments when code logic is unclear, implements workarounds, or has special reasoning that isn't immediately apparent to other developers. Comments should explain the "why" behind the implementation, not just the "what".

This includes:
- Documenting the rationale behind hacks or workarounds
- Explaining complex or non-intuitive logic flows  
- Providing context for special cases or edge case handling
- Linking to relevant issues or documentation when applicable

Example:
```javascript
// Fetch a dynamic import and re-try 3 times with a 2-second back-off
// See GitHub issue #1234 - this works around intermittent module loading failures
function retryImport(modulePath) {
  // implementation here
}

onStudioTestFileChange(filePath) {
  // wait for the studio test file to be written to disk, then reload the test
  return this.onTestFileChange(filePath).then(() => {
    // rest of implementation
  })
}
```

The goal is to make code self-documenting and reduce the cognitive load for future maintainers who need to understand the reasoning behind implementation decisions.

---

## maintain security constraints

<!-- source: python-poetry/poetry | topic: Security | language: Python | updated: 2023-03-06 -->

Always preserve existing security constraints and validation mechanisms rather than weakening them for convenience or functionality. When modifying authentication, validation, or security-related code, ensure that the changes maintain or strengthen the security posture.

Key principles:
- Don't bypass or weaken hash validation even when it seems unnecessary
- Maintain strict authentication precedence to prevent credential confusion
- Preserve security checks that prevent unauthorized access or data integrity issues

Example from hash validation:
```python
# Good: Maintain strict validation
known_hashes = {f["hash"] for f in package.files if f["file"] == archive.name}
if known_hashes and archive_hash not in known_hashes:
    # Still fails for security when no known hashes exist

# Bad: Weakening the constraint
if archive_hash not in known_hashes:  # Passes when known_hashes is empty
```

When in doubt about whether a security constraint is necessary, err on the side of maintaining it unless there's clear evidence it's safe to remove.

---

## Use descriptive names

<!-- source: cypress-io/cypress | topic: Naming Conventions | language: TypeScript | updated: 2023-03-02 -->

Choose names that clearly reveal the purpose and behavior of variables, functions, and methods. Names should be self-documenting and follow these patterns:

- **Boolean variables**: Use `is`, `has`, or `should` prefixes (e.g., `isInitialBuildSuccessful` instead of `diagnostics`)
- **Async methods**: Include action verbs that indicate the operation (e.g., `loadStorybookInfo()` instead of `storybookInfo`)  
- **Function parameters**: Use descriptive names instead of generic ones (e.g., `before, after` instead of `a, b`)
- **Test descriptions**: Avoid redundant words like "should" - prefer direct action descriptions (e.g., `"initializes"` instead of `"should initialize"`)

Example improvements:
```typescript
// Before
const diagnostics: boolean
async get storybookInfo()
function percentageDiff(a: number, b: number)

// After  
const diagnosticsEnabled: boolean
async loadStorybookInfo()
function percentageDiff(before: number, after: number)
```

Well-named code reduces the need for comments and makes the codebase more maintainable by clearly communicating intent to other developers.

---

## prioritize backward compatibility

<!-- source: cypress-io/cypress | topic: API | language: TSX | updated: 2023-02-21 -->

When evolving APIs, prioritize maintaining backward compatibility over enforcing strict design constraints. Teams should choose approaches that allow existing code to continue working rather than forcing breaking changes for theoretical purity.

This principle applies when:
- Relaxing API constraints to match real-world usage patterns
- Adding new features while supporting existing interfaces
- Choosing between strict enforcement and practical compatibility

For example, when a team discovered their API documentation required strict method chaining but developers commonly used direct calls, they chose to update the documentation to match actual usage rather than enforce the strict requirement:

```typescript
// Instead of forcing this breaking change:
cy.wrap(null).should(() => { /* assertions */ })

// They allowed the existing pattern:
cy.should(() => { /* assertions */ })
```

Similarly, when evolving from single-item to multi-item support, design the API to handle both cases uniformly rather than creating separate modes. Make the new interface accept arrays while treating single items as arrays of one, ensuring existing code continues to work without modification.

---

## Prefer semantic test selectors

<!-- source: cypress-io/cypress | topic: Testing | language: TSX | updated: 2023-02-14 -->

When writing tests, prioritize semantic and accessibility-based selectors over data attributes or generic selectors. Use accessible names, roles, and text content to select elements, as these selectors validate both functionality and accessibility simultaneously.

**Preferred approach:**
```javascript
// Good - validates both functionality and accessibility
cy.contains('button', 'Choose Editor').click()
cy.findByRole('button', { name: 'Save Settings' }).click()

// Acceptable when semantic selectors aren't sufficient
cy.get('[data-cy="choose-editor"]').click()

// Avoid - fragile and doesn't validate accessibility
cy.get('.btn-primary').click()
cy.get('button').first().click()
```

**Key benefits:**
- Tests fail when accessibility is broken (missing labels, incorrect roles)
- More resilient to styling changes that don't affect functionality
- Self-documenting - tests show expected user-facing behavior
- Encourages better accessibility practices in the codebase

**When to use data selectors:**
- Complex components where semantic selection is ambiguous
- Temporary testing during rapid prototyping (but update later)
- Cases where multiple elements share the same accessible name

Ensure your tests validate meaningful behavior rather than just element presence. A test that only checks if a component renders without validating its actual functionality provides limited value and may give false confidence.

---

## Verify documentation links

<!-- source: octokit/octokit.net | topic: Documentation | language: Markdown | updated: 2023-02-06 -->

Always ensure external links in documentation are valid, secure, and point to authoritative sources. This includes:

1. Use HTTPS instead of HTTP links for security
2. Verify that anchors within links actually exist at the destination
3. Link to official repositories and documentation rather than personal sites
4. Test all links before committing documentation changes

For example, instead of:
```markdown
Check out [this guide](http://personal-blog.com/outdated-page#non-existent-section) for more information.
```

Use:
```markdown
Check out [the official documentation](https://github.com/organization/project/blob/main/docs/guide.md#relevant-section) for more information.
```

Broken or insecure links reduce the credibility of documentation and create frustrating experiences for users. Regular verification of links ensures documentation remains reliable and trustworthy over time.

---

## Secure permission modeling

<!-- source: octokit/octokit.net | topic: Security | language: C# | updated: 2023-01-06 -->

When implementing security-related models such as permissions, carefully design the properties to prevent unauthorized modifications and maintain appropriate constraints:

1. Make security-sensitive properties immutable where possible using read-only properties or private setters:
```csharp
// Preferred
public bool Admin { get; }
// Or
public bool Admin { get; private set; }

// Avoid
public bool Admin { get; protected set; }
// Never
public bool Admin { get; set; }
```

2. When modeling permission values, consider the tradeoff between type safety and flexibility:
   - Use enums (StringEnum<PermissionLevel>) when values are strictly defined and limited
   - Use strings only when necessary (e.g., for custom roles in enterprise systems)
   - Document the rationale when moving from constrained types to more flexible ones

3. When expanding permission models, ensure backward compatibility while maintaining security guarantees.

Proper permission modeling reduces the risk of security vulnerabilities by preventing unintended permission modifications and providing compile-time safety where appropriate.

---

## Explain non-obvious code

<!-- source: cypress-io/cypress | topic: Documentation | language: TypeScript | updated: 2022-11-30 -->

Add explanatory comments for complex logic, workarounds, and non-obvious code patterns to help future maintainers understand the reasoning behind implementation decisions. Include links to external resources like GitHub issues, documentation, or source materials when relevant.

Key areas that need explanation:
- Complex regular expressions and their expected input/output
- Workarounds and why they're necessary (with GitHub issue links)
- Unusual approaches like postMessage usage
- Complex types copied from external libraries (with source links)
- Regression fixes (with links to the issues they address)

Example:
```typescript
// Workaround for macOS focus issues - see GitHub issue #12345
resetFocusIfMacOS () {
  // Implementation here
}

// Remove file extension from filename (e.g., "Component.vue" -> "Component")
return fileName.replace(/\....?$/, '')

// Using postMessage is necessary here because we need to communicate
// across different origins in a secure context
const onPostMessage = (event) => {
  // Implementation here
}
```

This practice ensures that complex or non-obvious code decisions are documented for future developers who need to maintain, debug, or extend the functionality.

---

## Informative error messages

<!-- source: cypress-io/cypress | topic: Error Handling | language: TypeScript | updated: 2022-11-30 -->

Error messages should be informative and include the actual values that caused the problem, not just generic descriptions. Use centralized error message utilities and ensure both the message and stack trace are properly updated.

Key practices:
- Include the actual problematic value in error messages (e.g., "expected function, got string" instead of just "expected function")
- Use accurate language that reflects the user's action (e.g., "tried to assign" vs "passed")
- Leverage error utilities like `$errUtils.modifyErrMsg` to ensure consistency between message and stack trace
- Centralize error messages in dedicated files (like error_messages.js) for consistent formatting

Example from the discussions:
```javascript
// Bad - vague and unhelpful
throw new Error('cy.session optional third argument must be an object')

// Good - includes actual problematic value
throw new Error(`cy.session optional third argument must be an object, you passed: ${typeof options}`)

// Better - uses proper error utilities and centralized messages
$errUtils.throwErrByPath('sessions.invalid_options', { 
  args: { expectedType: 'object', actualType: typeof options, actualValue: options } 
})
```

This approach helps developers quickly understand what went wrong and how to fix it, reducing debugging time and improving the development experience.

---

## Test version compatibility

<!-- source: cypress-io/cypress | topic: Testing | language: JSX | updated: 2022-11-30 -->

When testing across different versions of dependencies, proactively address version compatibility issues to prevent compilation failures and ensure proper behavior validation. Use mocking or stubbing techniques to resolve dependency conflicts, and explicitly test version-specific behaviors including error messages.

For compilation issues caused by version mismatches, consider using tools like `mock-require` or `proxyquire` to stub incompatible modules:

```javascript
// React 17 test that needs to handle React 18-only dependencies
// import React from 'react'
// Use conditional imports or mocking to handle version conflicts
import { mount } from 'cypress/react17' // version-specific import

// Test version-specific behaviors explicitly
describe('legacy mount behavior', () => {
  it('should provide helpful error message when using wrong version', () => {
    // Test that React18 mount gives appropriate error in React17 environment
  })
})
```

This approach prevents build failures while ensuring comprehensive testing of version-specific functionality and migration scenarios.

---

## function decomposition clarity

<!-- source: cypress-io/cypress | topic: Code Style | language: TypeScript | updated: 2022-10-28 -->

Functions should be focused, concise, and easy to understand. Break down large functions (>100 lines) into smaller, well-named functions that each handle a single responsibility. Remove unused parameters to reduce cognitive load and prevent confusion. Prefer functional programming patterns like `.some()`, `.map()`, and `.filter()` over imperative loops when they improve readability. Use proper async/await patterns instead of mixing promise styles.

Example of improvement:
```typescript
// Before: Large function with unused parameter
async function processData(data: any[], _unusedFlag?: boolean) {
  // 150+ lines of mixed logic
  let results = []
  data.forEach((item) => {
    if (item.isValid && item.hasPermission && item.isActive) {
      results.push(item)
    }
  })
  // more complex logic...
}

// After: Decomposed with functional patterns
async function processData(data: any[]) {
  const validItems = filterValidItems(data)
  const processedItems = await processItems(validItems)
  return formatResults(processedItems)
}

function filterValidItems(data: any[]) {
  return data.filter(item => 
    item.isValid && item.hasPermission && item.isActive
  )
}
```

This approach makes code more testable, readable, and maintainable by reducing complexity and making each function's purpose clear.

---

## Add missing code documentation

<!-- source: python-poetry/poetry | topic: Documentation | language: Python | updated: 2022-10-02 -->

Ensure all methods have docstrings and complex logic includes explanatory comments to help contributors understand code intent and functionality. Missing documentation creates barriers for new contributors and makes code maintenance more difficult.

For methods, add docstrings that describe the purpose and intended usage:
```python
def _group_by_source(self, deps: list[Dependency]) -> dict[str, list[Dependency]]:
    """Group dependencies by their source origin.
    
    Separates direct origin dependencies from non-direct origin dependencies
    to enable proper constraint merging logic.
    """
```

For complex logic, add comments explaining the reasoning and approach:
```python
# Group dependencies by source to apply different merge strategies
dep_groups = self._group_by_source(deps)
# Merge non-direct dependencies first, then combine with direct ones
# This ensures direct dependencies take precedence in constraint resolution
```

This documentation is especially valuable after refactoring, as it helps reviewers and future maintainers understand the improved logic without having to reverse-engineer the implementation.

---

## maintain API compatibility

<!-- source: evanw/esbuild | topic: API | language: Go | updated: 2022-09-19 -->

When implementing or extending APIs, preserve compatibility with existing standards and expected behaviors. APIs should maintain the same contracts, interfaces, and behavioral patterns as the systems they emulate or replace.

Key principles:
- Return results to callers rather than performing side effects directly (like file writing)
- Implement complete feature sets rather than partial implementations that break compatibility
- Use proper abstraction layers to maintain platform independence
- Respect fallback behaviors and edge cases from reference implementations
- Consider cross-platform and cross-browser compatibility when adding features

Example from bundler API design:
```go
// Bad: Bundler writes files directly, breaking API contract
defer ioutil.WriteFile(path.Join(targetFolder, url), []byte(source.Contents), 0644)

// Good: Return files to caller, preserving API contract
// Contents should be stashed on parseResult/ast and returned as BundleResult entry
```

This approach ensures APIs remain testable, predictable, and compatible with existing toolchains and workflows.

---

## Consider config generation methods

<!-- source: vercel/turborepo | topic: Configurations | language: Go | updated: 2022-09-09 -->

{% raw %}
When implementing code to handle configuration files like lockfiles or environment settings, carefully consider the trade-offs between direct serialization and template-based approaches. While direct serialization from data structures is often simpler and less error-prone, template-based generation may provide better control over formatting, whitespace sensitivity, and diffing capabilities. Document your reasoning when choosing an approach, especially when standard libraries have limitations (such as the Go YAML package's limited whitespace control). Consider how the consuming tools will interpret the generated files and whether preservation of specific formatting is important for your use case.

Example:
```go
// Template-based approach for better whitespace control
const pnpmLockfileTemplate = `lockfileVersion: {{ .Version }}

importers:
{{ range $key, $val := .Importers }}
  {{ $key }}:
{{ displayProjectSnapshot $val }}
{{ end }}
packages:
{{ range $key, $val :=  .Packages }}
  {{ $key }}:
{{ displayPackageSnapshot $val }}
{{ end }}{{ if (eq .Version 5.4) }}
{{ end }}`
```
{% endraw %}

---

## Use appropriate framework targets

<!-- source: octokit/octokit.net | topic: Configurations | language: Other | updated: 2022-08-10 -->

When configuring .NET projects, always use the correct target framework elements and versions:

1. Use the singular `<TargetFramework>` element when targeting a single framework:
```xml
<TargetFramework>netstandard2.0</TargetFramework>
```

2. Use the plural `<TargetFrameworks>` element only when targeting multiple frameworks:
```xml
<TargetFrameworks>netstandard2.0;net6.0</TargetFrameworks>
```

3. Always prefer Long Term Support (LTS) versions (like .NET 6) over non-LTS versions (like .NET 5) to ensure stability and longer support lifecycles. This reduces the frequency of required updates and provides more reliable runtime environments for production applications.

---

## Catch specific exceptions

<!-- source: octokit/octokit.net | topic: Error Handling | language: C# | updated: 2022-07-06 -->

Always catch specific exception types rather than using general catch blocks. This improves error handling precision, enables targeted recovery strategies, and maintains consistency across your codebase.

When implementing error handling:

1. **Catch specific exceptions** that you can meaningfully handle, not broad exception types
2. **Create custom exception types** for distinct error conditions rather than relying on string parsing
3. **Maintain consistency** with existing error handling patterns in your codebase

```csharp
// Avoid:
try {
    var httpStatusCode = await Connection.Delete(endpoint, new object(), AcceptHeaders.InvitationsApiPreview);
    return httpStatusCode == HttpStatusCode.NoContent;
} catch {
    return false; // Swallows ALL exceptions, including unexpected ones
}

// Preferred:
try {
    var httpStatusCode = await Connection.Delete(endpoint, new object(), AcceptHeaders.InvitationsApiPreview);
    return httpStatusCode == HttpStatusCode.NoContent;
} catch (NotFoundException) {
    // Only handle the specific case we expect and understand
    return false;
}

// When detecting specific error conditions, create custom exceptions:
if (body.Contains("secondary rate limit")) {
    // Don't rely on string matching
    throw new SecondaryRateLimitExceededException();
}
```

Catching specific exceptions ensures your error handling is predictable and that unexpected errors are properly propagated rather than silently ignored. This leads to more robust code that fails fast when encountering truly exceptional conditions.

---

## verify platform network compatibility

<!-- source: evanw/esbuild | topic: Networking | language: Other | updated: 2022-07-06 -->

When adding support for new platforms or architectures, thoroughly verify that networking functionality works correctly across different runtime environments and build configurations. This includes validating Go version requirements, cross-compilation toolchain compatibility, and runtime behavior differences.

Key verification steps:
1. Confirm minimum Go version requirements for target platforms (e.g., Go 1.19+ for loong64 architecture)
2. Test cross-compilation with proper toolchain setup, especially for mobile platforms requiring C compilers
3. Validate WebAssembly networking compatibility when deploying to browser environments
4. Verify that network protocols and connection handling work consistently across architectures

Example from the discussions:
```makefile
platform-linux-loong64:
	@$(MAKE) --no-print-directory GOOS=linux GOARCH=loong64 NPMDIR=npm/esbuild-linux-loong64 platform-unixlike
```

Before adding this target, verify that Go 1.19+ is available and that any networking libraries used in the application are compatible with the loong64 architecture. Similarly, for Android ARM builds, ensure the Android SDK C compiler is properly configured for any networking code that requires CGO.

---

## User-friendly network descriptions

<!-- source: alacritty/alacritty | topic: Networking | language: Markdown | updated: 2022-07-04 -->

When documenting network-related features like URL handling, hyperlinks, or web protocols, prioritize user-understandable descriptions over technical implementation details. Users care about what functionality they gain, not the internal mechanics of how it works.

Instead of technical descriptions like "Removal of characters before the URL scheme now take UTF8 byte sizes into account", use user-focused language like "Unicode characters at the beginning of URLs are now ignored". This helps users understand the practical impact of network-related changes.

For network protocol features, focus on the capability being added rather than the protocol specifics. For example, "Escape sequence to set hyperlinks" is clearer than detailing the exact OSC sequence format in user-facing documentation.

---

## Maintain consistent style

<!-- source: octokit/octokit.net | topic: Code Style | language: C# | updated: 2022-04-20 -->

Follow established patterns consistently throughout the codebase to improve readability and maintainability:

1. **Use auto properties with appropriate access modifiers**:
   - Prefer auto properties with private setters over readonly fields
   - Use private setters for properties set only in constructors
   ```csharp
   // Instead of:
   readonly string _title;
   
   // Prefer:
   public string Title { get; private set; }
   ```

2. **Follow constructor best practices**:
   - Required parameters only in constructors; use object initializers for optional values
   - Format parameterless constructors on a single line: `public ClassName() { }`
   - Ensure all properties are properly assigned in constructors

3. **Simplify code expressions**:
   - Prefer concise expressions over verbose alternatives
   ```csharp
   // Instead of:
   Assert.True(firstRefsPage.Where(x => secondRefsPage.Contains(x)).Any() == false);
   
   // Prefer:
   Assert.False(firstRefsPage.Any(x => secondRefsPage.Contains(x)));
   ```

4. **Be consistent with established patterns**:
   - Match the style used in surrounding code
   - Apply the same formatting rules throughout the project
   - Follow the project's conventions for organization and naming

---

## Algorithm selection correctness

<!-- source: evanw/esbuild | topic: Algorithms | language: Go | updated: 2022-04-19 -->

Choose algorithms that correctly match the problem requirements and understand their computational properties and side effects. Avoid using overly general solutions (like regex) when simpler, more precise algorithms exist.

Key principles:
1. **Match algorithm to problem domain**: Use domain-specific algorithms rather than general-purpose ones when precision matters. For example, TypeScript path mapping requires prefix/suffix matching, not regex pattern matching.

2. **Understand algorithmic side effects**: Operations like `p.findSymbol` may have side effects (marking usage) that affect other parts of the system. Document and account for these effects.

3. **Centralize complex algorithmic logic**: Place intricate algorithms like collision resolution in dedicated, well-audited locations rather than scattering the complexity across multiple passes.

Example of incorrect algorithm selection:
```go
// Incorrect: Using regex for simple pattern matching
if matched, err := regexp.MatchString("^"+key, path); matched && err == nil {
    // This treats '*' as regex repetition, not literal asterisk
}

// Correct: Use prefix/suffix matching like TypeScript compiler
func isPatternMatch(prefix, suffix, candidate string) bool {
    return len(candidate) >= len(prefix) + len(suffix) &&
           strings.HasPrefix(candidate, prefix) &&
           strings.HasSuffix(candidate, suffix)
}
```

Before implementing an algorithm, verify it handles edge cases correctly and matches the computational complexity requirements of your use case.

---

## Vue syntax parsing robustness

<!-- source: prettier/prettier | topic: Vue | language: JavaScript | updated: 2022-04-16 -->

When processing Vue components, ensure parsing logic handles edge cases correctly and selects appropriate parsers safely. This includes proper validation of directive syntax and careful parser selection based on explicit language declarations.

Key considerations:
- Avoid unsafe parser assumptions - TypeScript and JavaScript can parse the same code differently (e.g., `doSomething<T1 | T2>(param)` vs `(doSomething < T1) | (T2 > param)`)
- Only use TypeScript parser when `<script lang="ts">` is explicitly specified
- Handle empty or missing values in directive parsing - don't filter out falsy values that may be semantically meaningful
- Validate directive patterns before processing to prevent undefined returns

Example of problematic parsing:
```javascript
// This should not filter out the empty first iterator
const left = `${[res.alias, res.iterator1, res.iterator2]
  .filter(Boolean)  // ❌ Wrong - removes meaningful empty values
  .join(",")}`;

// For v-for="(,a,b) of 'abcd'" this incorrectly becomes "a,b" instead of ",a,b"
```

Proper validation should check for required components while preserving intentionally empty values in the syntax structure.

---

## Use descriptive testing names

<!-- source: cypress-io/cypress | topic: Testing | language: Json | updated: 2022-04-14 -->

Ensure all testing-related identifiers, scripts, and messages use clear, descriptive names rather than abbreviations or overly specific terminology. This improves maintainability and reduces confusion for both developers and users.

For script names, prefer explicit over abbreviated versions:
```json
// Good
"cypress:open": "ts-node ../../scripts/start.js --component-testing --project ${PWD}",
"cypress:run": "ts-node ../../scripts/start.js --component-testing --run-project ${PWD}",

// Avoid
"cy:open": "ts-node ../../scripts/start.js --component-testing --project ${PWD}",
"cy:run": "ts-node ../../scripts/start.js --component-testing --run-project ${PWD}",
```

For user-facing messages, use parameterized or generic terminology when possible to support multiple testing contexts:
```json
// Good - flexible for different testing types
"text": "You can reconfigure the {testingType} testing settings for this project if you're experiencing issues with your Cypress configuration."

// Avoid - too specific
"text": "You can reconfigure the component testing settings for this project if you're experiencing issues with your Cypress configuration."
```

This approach makes testing tooling more discoverable and user-facing content more reusable across different testing scenarios.

---

## Use optional patterns

<!-- source: vitejs/vite | topic: Null Handling | language: TypeScript | updated: 2022-04-01 -->

Choose the most appropriate pattern for handling potentially undefined or null values. When designing types, prefer optional properties (`?:`) over nullable types (`| null`) when a value is conceptually "not yet computed" rather than explicitly null.

For runtime null handling, use modern JavaScript features like nullish coalescing and optional chaining with idiomatic truthy checks:

```typescript
// Instead of nullable types with explicit initialization
class ModuleNode {
  isSelfAccepting: boolean | null = null;
}

// Prefer optional types
class ModuleNode {
  isSelfAccepting?: boolean;
}

// For runtime handling, use nullish coalescing
const listenOption = socket ?? { port, host: hostname };

// Use optional chaining with truthy checks
const rebase = pattern.match(/.*\/?node_modules\//)?.[0];
if (rebase) {
  // Do something with rebase
}
```

These patterns make code more concise, readable, and align with modern JavaScript idioms while maintaining type safety.

---

## Simplify complex expressions

<!-- source: cypress-io/cypress | topic: Code Style | language: Other | updated: 2022-02-28 -->

Break down complex conditional logic, nested structures, and verbose syntax into smaller, well-named functions or more concise expressions. This improves code readability and maintainability.

Key practices:
- Extract complex nested if/else statements into descriptive helper functions
- Use modern, idiomatic JavaScript/TypeScript syntax where available
- Replace verbose type annotations with more concise alternatives
- Break complex boolean conditions into named predicates

Example of improvement:
```typescript
// Instead of complex nested conditions:
if (err && err.showDiff !== false && err.expected !== undefined && _sameType(err.actual, err.expected)) {
  // ...
}

// Extract into named functions:
const diffCanBeShown = (err) => err && err.showDiff !== false
const hasExpectedValue = (err) => err.expected !== undefined
const hasSameTypeValues = (err) => _sameType(err.actual, err.expected)

const showDiff = (err) => diffCanBeShown(err) && hasExpectedValue(err) && hasSameTypeValues(err)
```

Also prefer concise TypeScript syntax:
```typescript
// Instead of: const docsMenuVariant: Ref<DocsMenuVariant> = ref('main')
const docsMenuVariant = ref<DocsMenuVariant>('main')
```

And use idiomatic JavaScript methods:
```typescript
// Instead of: indexOf() !== -1
// Use: includes()
```

---

## Document security policy trade-offs

<!-- source: cypress-io/cypress | topic: Security | language: Html | updated: 2022-01-19 -->

When implementing security policies like Content Security Policy (CSP), always include clear documentation explaining the reasoning behind each directive choice and any security trade-offs being made. This prevents confusion during code reviews and ensures team members understand the security implications.

For example, when using less secure CSP directives, document why they're necessary:

```html
<!--
  Using 'unsafe-inline' instead of 'self' because we need to allow inline <script> tags.
  Trade-off: 'self' would be more secure but throws errors for inline scripts.
  This configuration fixes issue #3785 without reintroducing #19697.
-->
<meta http-equiv="Content-Security-Policy" content="script-src 'unsafe-inline'" />
```

This practice helps maintain security awareness across the team and provides context for future modifications to security configurations.

---

## avoid redundant I/O operations

<!-- source: cypress-io/cypress | topic: Performance Optimization | language: TypeScript | updated: 2021-12-07 -->

Identify and eliminate repeated expensive operations, particularly file system access, by implementing caching, batching, or data sharing strategies. When the same file or resource is accessed multiple times within a short timeframe, consider caching the result or restructuring the code to perform the operation once and reuse the data.

For example, instead of reading the same file multiple times for each test:
```typescript
// Problematic: reads file for each test
export const getStudioDetails = async (fileDetails: FileDetails) => {
  return {
    studioExtended: await wasTestExtended(fileDetails).catch(() => false),
    studioCreated: await wasTestCreated(fileDetails).catch(() => false),
  }
}
```

Consider caching the file content or combining the operations:
```typescript
// Better: read file once and share the data
export const getStudioDetails = async (fileDetails: FileDetails) => {
  const fileContent = await readFileOnce(fileDetails);
  return {
    studioExtended: checkIfExtended(fileContent),
    studioCreated: checkIfCreated(fileContent),
  }
}
```

This is especially critical when operations scale with the number of tests or files, as the performance impact compounds significantly.

---

## prefer modern composition patterns

<!-- source: cypress-io/cypress | topic: Vue | language: Other | updated: 2021-11-03 -->

Use Vue 3 Composition API patterns that provide better performance, type safety, and maintainability. Prefer `computed` over `watch` + reactive assignment when deriving values from other reactive data. Use `defineEmits` instead of `$emit` in templates for type safety. Adopt modern `defineProps<{}>()` syntax over PropType casting for better TypeScript inference and performance. Consider `watchEffect` when you need `watch` with `immediate: true`.

Examples:
```ts
// ❌ Avoid watch + assignment pattern
const promptToShow = ref('')
watch(savedState, (newVal) => {
  promptToShow.value = computePrompt(newVal)
})

// ✅ Use computed for derived values
const promptToShow = computed(() => {
  return computePrompt(savedState.value)
})

// ❌ Avoid $emit in templates
@click="$emit('removeProject', props.gql.projectRoot)"

// ✅ Use defineEmits for type safety
const emit = defineEmits<{
  (e: 'removeProject', path: string): void
}>()
@click="emit('removeProject', props.gql.projectRoot)"

// ❌ Avoid PropType casting
const props = defineProps({
  gql: {
    type: Object as PropType<PackagesListFragment>,
    required: true
  }
})

// ✅ Use generic syntax for better inference
const props = defineProps<{
  gql: PackagesListFragment
}>()

// ✅ Use watchEffect for immediate watching
watchEffect(() => {
  docsMenuVariant.value = props.forceOpenDocs ? 'ci1' : 'main'
})
```

These patterns reduce boilerplate, improve TypeScript performance in IDEs, provide better type safety, and align with Vue 3 best practices.

---

## Consistent naming patterns

<!-- source: cypress-io/cypress | topic: Naming Conventions | language: Other | updated: 2021-11-03 -->

Establish and enforce consistent naming conventions across different contexts in your codebase. Teams should decide on specific patterns and use linting to maintain consistency rather than mixing approaches.

Key areas to standardize:

**Props access**: Choose either `props.showBrowsers` or destructured `showBrowsers` consistently throughout the codebase. As noted in discussions: "we should lint for one or the other" rather than mixing both approaches.

**Component naming**: Use PascalCase for custom Vue components (`RouterLink`) and kebab-case for native HTML elements and built-in Vue components (`router-link`). Avoid mixing casing styles within the same context.

**GraphQL fragments**: Adopt a consistent naming pattern like `ComponentName_UniqueName` for all fragments, even when there's only one per component. This prevents naming conflicts and maintains predictability.

Example of inconsistent vs consistent patterns:
```vue
<!-- Inconsistent -->
<template>
  <router-link :to="props.href">  <!-- mixing kebab-case component with props. access -->
    <HeaderContent :show-browsers="showBrowsers" />  <!-- mixing destructured props -->
  </router-link>
</template>

<!-- Consistent -->
<template>
  <RouterLink :to="href">  <!-- PascalCase for custom components -->
    <HeaderContent :show-browsers="showBrowsers" />  <!-- consistent props access -->
  </RouterLink>
</template>
```

The goal is to eliminate decision fatigue and reduce cognitive load by having clear, lintable rules that the entire team follows consistently.

---

## Prioritize naming clarity

<!-- source: cypress-io/cypress | topic: Naming Conventions | language: Json | updated: 2021-11-03 -->

Choose names and aliases that clearly communicate their purpose and meaning rather than optimizing for brevity or perceived elegance. Avoid abbreviated aliases that obscure the actual location or purpose of code elements, and resist adding premature complexity like numerical suffixes unless multiple variants actually exist.

For example, prefer explicit paths like `@packages/frontend-shared/src/gql-components` over cryptic aliases like `@cy/components` that require developers to mentally map the alias to its actual location. Similarly, use simple names like `ci` until you actually need `ci1` and `ci2` - don't add complexity in anticipation of future needs that may never materialize.

The goal is to make code self-documenting where a developer can understand what something is and where it comes from without needing to look up aliases or decipher naming conventions.

---

## Avoid brittle CSS patterns

<!-- source: cypress-io/cypress | topic: Code Style | language: Css | updated: 2021-10-29 -->

Write CSS that prioritizes maintainability and reduces the likelihood of conflicts or brittleness. This includes using semantic class names instead of raw HTML element selectors, and avoiding explicit z-index values when possible.

Raw HTML selectors like `span:last-child button` and `span` are more brittle and harder to understand than semantic class names. Similarly, explicit z-index values like `z-index: 99999` can lead to stacking conflicts where developers "find themselves fighting with their own code on who's on top."

Instead, prefer:
- Semantic class names that clearly describe the component's purpose
- Natural document order and portal-based stacking for z-index management
- CSS patterns that are self-documenting and less likely to break when the HTML structure changes

Example of brittle pattern:
```css
span:last-child button,
.play {
  padding: 1px 10px;
}

.ui-blocker {
  z-index: 99999; /* Explicit z-index can cause conflicts */
}
```

Better approach:
```css
.header-action-button,
.play-button {
  padding: 1px 10px;
}

.ui-blocker {
  /* Rely on natural stacking order instead of explicit z-index */
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
}
```

---

## GraphQL mutation design

<!-- source: cypress-io/cypress | topic: API | language: TypeScript | updated: 2021-10-18 -->

Design GraphQL mutations to return meaningful objects rather than simple booleans, and use simple ID parameters instead of complex nested objects. This follows GraphQL best practices and enables proper client-side cache management.

**Return Objects from Mutations:**
Mutations should return the modified entity to enable Apollo Client's normalized cache to update automatically. Returning just `true` or simple scalars requires manual cache updates.

```ts
// ❌ Avoid - returns boolean, requires manual cache updates
t.nonNull.field('addProject', {
  type: 'Boolean',
  async resolve(_root, args, ctx) {
    await ctx.projects.addProject(args)
    return true
  }
})

// ✅ Prefer - returns Project object for automatic cache updates
t.nonNull.field('addProject', {
  type: 'Project',
  async resolve(_root, args, ctx) {
    const project = await ctx.projects.addProject(args)
    return project
  }
})
```

**Use Simple ID Parameters:**
Prefer simple ID arguments over complex nested objects to keep the API clean and leverage server-side knowledge of entity relationships.

```ts
// ❌ Avoid - complex nested object parameter
t.nonNull.field('setCurrentSpec', {
  args: {
    spec: nonNull(inputObjectType({ /* complex spec object */ }))
  }
})

// ✅ Prefer - simple ID parameter
t.nonNull.field('setCurrentSpec', {
  args: {
    specId: nonNull(idArg())
  }
})
```

This approach reduces API complexity, improves type safety, and follows GraphQL conventions for client-server communication.

---

## consistent descriptive naming

<!-- source: cypress-io/cypress | topic: Naming Conventions | language: JavaScript | updated: 2021-10-12 -->

Maintain consistent naming patterns across similar functionality while ensuring names accurately describe their current purpose and scope. When multiple options exist for the same feature, standardize on one clear option to avoid confusion in documentation and usage. Update variable names when their type or purpose changes, and use descriptive names that clearly indicate scope and function.

Examples:
- Standardize on `--component` instead of supporting both `--component` and `--ct` flags
- Rename `written` to `writtenChunkCount` when changing from boolean to counter
- Use consistent namespacing like `/__cypress/bundled` to match existing conventions
- Name debug variables consistently as `debugVerbose` even when no non-verbose version exists
- Update labels like "All Specs" to "All Integration Specs" when context requires specificity

This prevents inconsistent documentation, reduces cognitive load for developers, and ensures the codebase remains predictable and maintainable.

---

## Choose appropriate log levels

<!-- source: cypress-io/cypress | topic: Logging | language: JavaScript | updated: 2021-10-12 -->

Select log levels based on the intended audience and actionability of the message. Use `debug` for internal development information that helps with troubleshooting, `warn` or `error` for user-actionable issues, and avoid logging messages that add noise without providing value to the user.

Key principles:
- Don't log messages users cannot act upon - this creates noise in console output
- Use `debug` logs for internal state and development information
- Ensure log formatting doesn't depend on specific log levels being enabled
- User-facing logs should provide clear, actionable information

Example:
```javascript
// Good: Internal information for developers
debug('launch project')

// Good: User-actionable warning
logger.warn(stripIndent(msg))

// Avoid: Noise that users can't act on
console.warn(`Could not get the original source file from line "${line}"`)
```

When in doubt, prefer `debug` logs for internal information and reserve user-facing logs for messages that require user attention or action.

---

## ensure async synchronization

<!-- source: cypress-io/cypress | topic: Concurrency | language: Other | updated: 2021-08-30 -->

When dealing with async operations that depend on external systems (servers, backends, etc.), ensure proper synchronization to avoid race conditions. Don't rely on client-side polling or workarounds when the root cause is improper async handling.

Key principles:
- Make functions async when they need to wait for external operations to complete
- Use proper sequencing for initialization dependencies
- Ensure server acknowledgment before proceeding with dependent operations

Example of proper async sequencing:
```js
// Instead of client-side polling workarounds
async function start(openElectron) {
  await initializeThings()
  openElectron()
}

// Make functions async when they need to ensure completion
async function reset() {
  await Cypress.backend("set:traffic:routing:reset")
}
```

This prevents race conditions where the UI renders before the backend is ready, or where operations proceed without confirming the previous step completed successfully.

---

## Strengthen test assertions

<!-- source: cypress-io/cypress | topic: Testing | language: JavaScript | updated: 2021-08-02 -->

Write specific, regression-proof test assertions that validate exact expected values rather than allowing ambiguous matches. Avoid assertions that could pass with incorrect but similar values.

**Problems with weak assertions:**
- `expect(a).eq(b)` passes even if both are `undefined`
- Comparing two dynamic values that could both be wrong
- Missing type validation that could catch unexpected data types

**Better assertion patterns:**

```javascript
// Instead of just comparing two potentially undefined values
expect(Cypress.currentTest.title).eq(cy.state('runnable').ctx.currentTest.title)

// Add type validation and literal value checks
expect(Cypress.currentTest.title)
  .to.be.a('string')
  .eq(cy.state('runnable').title)
  .eq('returns current test runnable properties')
```

**Key improvements:**
1. **Type validation**: Use `.to.be.a('string')` to ensure expected data types
2. **Literal comparisons**: Compare against known string literals when possible
3. **Multiple assertions**: Chain assertions to validate different aspects
4. **Avoid symmetric comparisons**: Don't just compare two dynamic values that could both be wrong

This approach makes tests more reliable by catching edge cases where both compared values might be incorrect in the same way, and provides clearer failure messages when assertions fail.

---

## await promise-returning functions

<!-- source: cypress-io/cypress | topic: Concurrency | language: TypeScript | updated: 2021-07-19 -->

Always await functions that return promises to ensure proper asynchronous execution and avoid potential race conditions or unexpected behavior. When converting from promise chains to async/await, verify that all promise-returning function calls include the await keyword.

Common mistake: Calling a promise-returning function without await, which can lead to unhandled promises and timing issues.

```ts
// ❌ Incorrect - missing await
export const showDialogAndCreateSpec = async () => {
  const cfg = openProject.getConfig()
  const path = await showSaveDialog(cfg.integrationFolder)
  
  if (path) {
    createFile(path) // Missing await - promise not handled
  }
}

// ✅ Correct - properly awaited
export const showDialogAndCreateSpec = async () => {
  const cfg = openProject.getConfig()
  const path = await showSaveDialog(cfg.integrationFolder)
  
  if (path) {
    await createFile(path) // Properly awaited
  }
}
```

This is especially important when refactoring from promise chains (.then()) to async/await syntax, as it's easy to overlook promise-returning functions that need to be awaited.

---

## Safe null access patterns

<!-- source: cypress-io/cypress | topic: Null Handling | language: Other | updated: 2021-07-14 -->

Always provide fallbacks when accessing properties or methods on values that could be undefined or null to prevent runtime errors. Use defensive programming patterns like logical OR operators, conditional checks, or nullish coalescing when available.

Examples of unsafe patterns:
```javascript
// Unsafe - could throw if renderProps is undefined
const showMarkdown = computed(() => props.command.renderProps && props.command.renderProps.message)

// Unsafe - could throw if message/markdown is undefined
scaled: computed(() => (props.message || props.markdown).length > 100)
```

Examples of safe patterns:
```javascript
// Safe - provides fallback value
const showMarkdown = computed(() => props.command.renderProps?.message ?? false)
// Or without optional chaining:
const showMarkdown = computed(() => props.command.renderProps && props.command.renderProps.message || false)

// Safe - provides empty string fallback
scaled: computed(() => (props.message || props.markdown || '').length > 100)
```

This prevents common runtime errors like "Cannot read property 'x' of undefined" and makes code more robust when dealing with optional or potentially missing data.

---

## Use exact dependency versions

<!-- source: cypress-io/cypress | topic: Configurations | language: Json | updated: 2021-06-25 -->

Always specify exact dependency versions in package.json files instead of using version ranges (^, ~) to ensure reproducible builds and prevent accidental upgrades that could introduce breaking changes.

When adding new dependencies or updating existing ones, pin to specific versions to maintain build consistency across environments. This is especially important for production applications where unexpected dependency updates could cause runtime issues.

Example:
```json
// ❌ Avoid version ranges
"dependencies": {
  "snap-shot-core": "^7.4.0",
  "diff": "^4.0.1"
}

// ✅ Use exact versions
"dependencies": {
  "snap-shot-core": "7.4.0", 
  "diff": "4.0.1"
}
```

Remember that configuration changes may require additional dependencies - for example, enabling `"importHelpers": true` in tsconfig.json requires adding `tslib` as an exact dependency. Always verify that configuration changes don't introduce missing dependency requirements.

---

## minimize test maintenance

<!-- source: evanw/esbuild | topic: Testing | language: Go | updated: 2021-06-08 -->

Avoid unnecessary test maintenance overhead by eliminating duplicate test coverage and implementing automated test update mechanisms. When the same functionality is already covered by equivalent tests (e.g., end-to-end tests that exercise the same code paths), remove redundant test implementations rather than maintaining multiple versions. Additionally, design test assertions and output systems to support automated updates rather than requiring manual copy-paste workflows.

For example, instead of maintaining both JavaScript and Go plugin tests when "the API calls in each JavaScript plugin are forwarded through a Go plugin," keep only the more comprehensive end-to-end tests. Similarly, implement snapshot-style testing systems that can automatically update expected outputs rather than requiring developers to manually copy test results.

This approach reduces maintenance burden, prevents test drift between duplicate implementations, and allows developers to focus on meaningful test coverage rather than repetitive maintenance tasks.

---

## standardize API patterns

<!-- source: cypress-io/cypress | topic: API | language: JavaScript | updated: 2021-06-04 -->

Establish consistent patterns for API design, particularly for request/response formats and parameter structures. This improves predictability, type safety, and developer experience across the codebase.

For communication interfaces, use standardized payload structures:

```js
{
  type: 'success' | 'error',
  data: any,
  event: string
}
```

For method parameters, prefer explicit options objects over method chaining when configuration is complex:

```js
// Preferred: explicit options
agent.log = (options) => {
  if (options && options.snapshot === false) {
    // handle configuration
  }
}

// Instead of: method chaining
agent.snapshot(false).log()
```

This approach makes APIs more readable, self-documenting, and easier to extend without breaking existing functionality. Consistent patterns also enable better tooling support and type checking.

---

## Document CI pipeline comprehensively

<!-- source: Homebrew/brew | topic: CI/CD | language: Markdown | updated: 2021-05-19 -->

Ensure CI/CD pipeline documentation accurately reflects the complete workflow, including job dependencies, execution order, and all operations performed by each step. When documenting CI processes:

1. List CI jobs in their logical execution order, with dependency relationships clearly indicated
2. Document all operations performed by each job, not just the primary ones
3. Specify clear conditions for when different CI-related tools should be used

For example, when documenting a test job that runs multiple commands:

```markdown
## CI Jobs

- `CI / syntax`: This is run first to check whether the PR passes `brew style` and `brew typecheck`. If this job fails, the following jobs will not run.
- `CI / test everything (macOS)`: This runs multiple tests including:
  - `brew tests`
  - `brew update-tests`
  - `brew readall`
  - `brew test-bot --only-formulae --test-default-formula`
  - `brew doctor`
```

Complete documentation helps maintainers understand the full CI pipeline, troubleshoot failures effectively, and follow consistent processes when merging changes.

---

## Evaluate security control effectiveness

<!-- source: Homebrew/brew | topic: Security | language: Markdown | updated: 2021-05-17 -->

Security measures should be evaluated against realistic threat models to avoid creating a false sense of security. When implementing security controls like checksums, consider whether they actually protect against likely attack vectors.

For example, in package management systems that download from third-party sources:

```
# INSUFFICIENT SECURITY:
# The sha256 verification provides limited protection if the attacker can control both:
# - The download URL source
# - Version information being reported

# Better approach: Implement defense-in-depth with multiple complementary security controls
# - Digital signatures from trusted authorities
# - Reproducible builds to verify package contents
# - Monitoring for unexpected behavior or changes
```

Remember that sophisticated attackers target the weakest links in your security chain. If they can compromise one control (like a download URL), they can often compromise related controls (like version reporting), rendering single verification methods inadequate.

---

## Consistent formatting preferences

<!-- source: cypress-io/cypress | topic: Code Style | language: JavaScript | updated: 2021-05-10 -->

Follow consistent formatting and syntax patterns to improve code readability and maintainability. This includes using compact formatting for test blocks, proper quote usage, positive-first conditionals, and preferred syntax patterns.

Key formatting guidelines:
- Use compact formatting for describe/it blocks: `describe('errors', { defaultCommandTimeout: 50 }, () => {`
- Prefer double quotes over escaped single quotes: `"foo"` instead of `'foo\'`  
- Put positive conditions first in if statements: `if (state.initialBuildSucceed) { ... } else { ... }`
- Use direct return expressions: `return (expression)` instead of `if (...) return true`
- Prefer `.catch()` syntax over try/catch blocks for promise handling
- Use proper eslint disable patterns: `/* global jest */` at file top instead of inline `eslint-disable-next-line no-undef`

These patterns make code more readable and follow modern JavaScript conventions while reducing cognitive load for developers.

---

## optimize dynamic loading

<!-- source: cypress-io/cypress | topic: Performance Optimization | language: JavaScript | updated: 2021-04-26 -->

When using dynamic imports, implement timing controls and strategic naming to ensure reliable and efficient resource loading. Use minimal delays (like setTimeout with 0ms) to control initialization timing and prevent race conditions that could cause failures. Additionally, use descriptive chunk names with webpackChunkName comments to create readable, manageable bundles that improve system organization and API handling.

Example:
```javascript
// Use timing control to ensure proper initialization
const importsToLoad = [() => {
  return new Promise((resolve) => {
    setTimeout(() => {
      import(/* @vite-ignore */ specPath).then(resolve)
    }, 0) // Use 0ms for next tick timing
  })
}]

// Use descriptive chunk names for better organization
const eventManager = await import(/* webpackChunkName: "ctChunk-EventManager" */'./event-manager')
  .then((module) => module.default)
```

This approach prevents resource loading failures while maintaining organized, performant code splitting that benefits both development and runtime performance.

---

## Prioritize JSX readability

<!-- source: cypress-io/cypress | topic: React | language: TSX | updated: 2021-03-30 -->

Favor inline conditional rendering in JSX over extracting logic to variables before the return statement, as it maintains better flow control visibility and reduces cognitive overhead when reading components. Additionally, use descriptive variable names that clearly convey their purpose and state.

For conditional rendering, prefer:
```tsx
return (
  <div>
    {state.specs.length < 1 
      ? <NoSpec />
      : <SpecList />
    }
  </div>
)
```

Over extracting to variables:
```tsx
const specListContent = state.specs.length < 1 
  ? <NoSpec />
  : <SpecList />

return (
  <div>
    {specListContent}
  </div>
)
```

The inline approach keeps the rendering logic visible in context, making it easier to understand what gets rendered without jumping between variable definitions. For variable naming, choose names that clearly indicate the variable's role - for example, use `isRunning` instead of `isLive` when the variable represents whether a process is currently executing.

---

## Extract inline code

<!-- source: cypress-io/cypress | topic: Code Style | language: TSX | updated: 2021-03-29 -->

Extract complex inline code elements into separate functions, components, or constants to improve readability and maintainability. This includes hardcoded strings, complex event handlers, and lengthy JSX expressions.

Examples of what to extract:
- Hardcoded strings: Move to constants or props instead of inline literals
- Complex event handlers: Extract into separate functions rather than defining inline
- Complex JSX expressions: Pull into separate components when they contain significant logic or styling

```js
// Instead of inline handler:
onClick={(e) => {
  props.onClick(e, props.item)
  onClick(e, props.item)
}}

// Extract to function:
function handleClick(e) {
  props.onClick(e, props.item)
  if (props.item.onClick) {
    props.item.onClick(e, props.item)
  }
}
```

This practice makes code more testable, reusable, and easier to understand by giving meaningful names to code blocks and reducing visual complexity in the main component logic.

---

## Prefer standard terminology

<!-- source: cypress-io/cypress | topic: Naming Conventions | language: JSX | updated: 2020-12-20 -->

Use widely accepted industry-standard names and conventions rather than descriptive but non-standard alternatives. This improves code readability and maintainability by leveraging established terminology that developers are already familiar with.

For components, prefer established UI terminology over descriptive names:
```jsx
// Avoid descriptive but non-standard names
const UiBlocker = () => { /* ... */ }

// Prefer widely accepted industry terms  
const Scrim = () => { /* ... */ }
```

For file extensions, use standard conventions consistently:
```
// Prefer standard extensions for new files
CollapseIcon.tsx  // instead of CollapseIcon.jsx
```

This approach reduces cognitive load for developers who can immediately understand the purpose and behavior based on familiar naming patterns from the broader development community.

---

## structured debug logging

<!-- source: cypress-io/cypress | topic: Logging | language: Other | updated: 2020-05-26 -->

Use structured logging with object notation instead of string interpolation for debug messages to improve readability and provide better structured data. This approach makes logs more consistent and easier to parse, while also helping to consolidate related information into single log statements.

Instead of using string interpolation with multiple parameters:
```coffeescript
debug("plugins file %s is default, check if folder %s exists", pluginsFile, path.dirname(pluginsFile))
```

Use structured logging with objects:
```coffeescript
debug("checking if pluginsFile exists", { pluginsFile, dirName: path.dirname(pluginsFile) })
```

This format groups related data together, reduces the need for multiple debug statements, and makes the logs more readable. When possible, consolidate multiple related debug messages into fewer, more informative structured logs to avoid duplication across modules.

---

## Design intuitive API methods

<!-- source: octokit/octokit.net | topic: API | language: C# | updated: 2020-04-14 -->

When designing API methods, prioritize intuitive usage patterns and backwards compatibility. Follow these guidelines:

1. Order parameters from required to optional, maintaining consistency across overloads:
```csharp
// Good - consistent parameter order
public Task<RepositoryContent> GetAllContents(string owner, string name, string reference);
public Task<RepositoryContent> GetAllContents(string owner, string name, string reference, string path);

// Bad - inconsistent parameter order
public Task<RepositoryContent> GetAllContents(string owner, string name, string path, string reference);
```

2. Use clear, singular property names for sub-clients:
```csharp
// Good
public IObservableTeamDiscussionsClient Discussion { get; }

// Bad 
public IObservableTeamDiscussionsClient TeamDiscussion { get; }
```

3. When adding new parameters or changing existing ones:
- Add new overloads rather than modifying existing method signatures
- Keep existing methods for backwards compatibility
- Mark deprecated methods with [Obsolete] attribute and direct users to new methods

4. Include clear XML documentation describing parameter usage and any authentication requirements

This approach ensures APIs remain intuitive to use while maintaining compatibility for existing consumers.

---

## Use precise networking terminology

<!-- source: cypress-io/cypress | topic: Networking | language: Other | updated: 2020-02-18 -->

When writing error messages or documentation related to network requests and cross-origin policies, use precise terminology that accurately describes the scope of the issue. Prefer "URL" over "domain" when the problem could involve any URL component (protocol, port, path, etc.), not just the domain name. Use proper technical terms like "origin" when discussing same-origin policy violations.

For example, instead of:
```
A cross origin error happens when your application navigates to a new superdomain which does not match the origin policy above.
```

Use:
```
A cross origin error happens when your application navigates to a new URL which does not match the origin policy above.
```

This precision helps developers understand that the issue isn't limited to just domain changes but could involve protocol, port, or other URL components. Additionally, use proper grammar with articles ("a different origin" rather than "different origin") and hyphenate compound technical terms ("same-origin URLs") for clarity and consistency with web standards terminology.

---

## Clear security error messages

<!-- source: cypress-io/cypress | topic: Security | language: Other | updated: 2020-02-04 -->

When implementing security restrictions or policies, ensure error messages clearly explain what the security boundary is, why it exists, and what specifically triggered the violation. Vague or technical jargon can leave developers confused about security requirements.

Security error messages should include:
- The specific policy or restriction that was violated
- What action triggered the security error
- Clear explanation of the security boundary (e.g., origin policy, authentication requirements)
- Reference to relevant documentation when the concept is complex

Example of improvement:
```
// Before: Vague message
"A cross origin error happens when your application navigates to a new superdomain"

// After: Clear and specific
"A cross origin error happens when your application navigates to a new domain which does not match the origin policy above.
Cypress does not allow you to navigate to different origin within a single test.
An origin is defined by protocol + host + port."
```

This approach helps developers understand security constraints and work within them effectively, rather than being blocked by cryptic error messages.

---

## Improve code expressiveness

<!-- source: cypress-io/cypress | topic: Code Style | language: JSX | updated: 2019-10-16 -->

Write code that clearly communicates its intent through expressive method names and simplified control flow. Replace complex inline conditions with descriptive method calls that encapsulate the logic, and use early returns to reduce cyclomatic complexity and focus functions on their primary responsibility.

Key practices:
- Encapsulate complex conditions in well-named methods (e.g., `project.isBrowserState(Project.BROWSER_OPEN)` instead of `project.browserState === 'opened'`)
- Use early returns to handle edge cases first, allowing the main logic to be the focus
- Choose method names that clearly express what they check or do

Example:
```javascript
// Before: Complex inline condition
if (project.browserState === 'opened' || project.browserState === 'opening') {
  // main logic
}

// After: Expressive method encapsulation
if (project.isBrowserState(Project.BROWSER_OPENING, Project.BROWSER_OPEN)) {
  // main logic
}

// Before: Nested conditional logic
function _closeBrowserBtn() {
  if (this.props.project.browserState === 'opened') {
    return (
      <li className='close-browser'>
        // button JSX
      </li>
    )
  }
}

// After: Early return with expressive method
function _closeBrowserBtn() {
  if (!this.props.project.isBrowserState(Project.BROWSER_OPEN)) return null
  
  return (
    <li className='close-browser'>
      // button JSX  
    </li>
  )
}
```

This approach makes code more readable, maintainable, and self-documenting while reducing complexity.

---

## Use async/await pattern

<!-- source: octokit/octokit.net | topic: API | language: Markdown | updated: 2019-02-20 -->

When designing or documenting API clients, always use the async/await pattern rather than blocking calls. Replace code that uses `.GetAwaiter().GetResult()` with proper async/await syntax to prevent potential deadlocks and improve application responsiveness.

Example:
```csharp
// Instead of this:
Repository octokitRepo = ghClient.Repository.Get("octokit", "ocktokit.net").GetAwaiter().GetResult();

// Use this:
var octokitRepo = await ghClient.Repository.Get("octokit", "ocktokit.net");
```

Additionally, ensure method names clearly describe their API operation (e.g., 'CreatePullRequestFromFork' instead of 'CreatePR') to improve code readability and API usability.

---

## Choose appropriate type comparisons

<!-- source: cypress-io/cypress | topic: Algorithms | language: Other | updated: 2019-01-22 -->

When implementing algorithms that compare or process different data types, carefully consider the level of type strictness required for your use case. Overly strict type checking (like `Object.prototype.toString`) may prevent useful operations, while overly loose checking may produce meaningless results.

For diff algorithms and similar comparison operations, prefer `typeof` over `Object.prototype.toString` when you want to enable comparisons between objects of different classes but the same JavaScript type. This allows meaningful diffs between `MouseEvent {clientX: 39, clientY: 50}` and `Object {clientX: 40, clientY: 50}` since both are objects.

However, ensure your conditional logic properly handles mixed data types. When comparing strings to objects, verify that your algorithm gracefully handles or explicitly rejects such comparisons rather than producing confusing output.

```coffeescript
# Too strict - prevents useful comparisons
_sameType = (a, b) ->
  return objToString.call(a) is objToString.call(b)

# Better - allows comparisons between different object classes
_sameType = (a, b) ->
  return typeof a is typeof b
```

Consider the downstream impact of your type comparison choice on the overall algorithm's utility and user experience.

---

## Use nullable for optionals

<!-- source: octokit/octokit.net | topic: Null Handling | language: C# | updated: 2018-11-07 -->

When a property or parameter represents an optional value that might be absent in requests or responses, use nullable types rather than non-nullable types with default values. This clearly distinguishes between "not set" and an explicit value, prevents sending unintended defaults in API requests, and properly handles missing values in API responses.

For boolean flags that are optional in API requests:
```csharp
// INCORRECT: Will always send a value (false by default)
public bool MaintainerCanModify { get; set; }

// CORRECT: Only sent when explicitly set by the user
public bool? MaintainerCanModify { get; set; }
```

For enum-like values that might be absent in API responses:
```csharp
// INCORRECT: Will cause issues when API returns null
public StringEnum<EmailVisibility> Visibility { get; protected set; }

// CORRECT: Properly handles missing values in responses
public StringEnum<EmailVisibility>? Visibility { get; protected set; }
```

This pattern also applies to optional fields in database models, DTOs, and any other context where a value might legitimately be absent. Using nullable types communicates intent clearly and prevents subtle bugs from default values being interpreted as explicit choices.

---

## synchronize platform configurations

<!-- source: alacritty/alacritty | topic: Configurations | language: Yaml | updated: 2018-08-22 -->

When making configuration changes that affect multiple platform-specific files, ensure all related configuration files are updated consistently and test the changes on each target platform.

Configuration changes often need to be replicated across platform-specific variants (e.g., `alacritty.yml` and `alacritty_macos.yml`). Failing to synchronize these files can lead to inconsistent behavior across platforms and user confusion.

Always identify and update all related configuration files when making changes. Additionally, verify that configuration changes work as expected on each target platform, as platform-specific behaviors can differ even with identical configuration syntax.

Example:
```yaml
# alacritty.yml
key_bindings:
  - { key: Equals,   mods: Control, action: IncreaseFontSize }
  - { key: Subtract, mods: Control, action: DecreaseFontSize }

# alacritty_macos.yml (must be updated consistently)
key_bindings:
  - { key: Equals,   mods: Command, action: IncreaseFontSize }
  - { key: Subtract, mods: Command, action: DecreaseFontSize }
```

Test configuration changes on the actual target platforms rather than assuming cross-platform compatibility, as modifier keys and system behaviors can vary between operating systems.

---

## Consistent naming patterns

<!-- source: octokit/octokit.net | topic: Naming Conventions | language: C# | updated: 2018-08-10 -->

Follow consistent naming conventions throughout the codebase to improve readability and maintainability:

1. **Client property names should be singular**, not plural:
```csharp
// Good
IObservableOrganizationHooksClient Hook { get; }
// Not
IObservableOrganizationHooksClient Hooks { get; }
```

2. **Method names should include appropriate verbs** and be concise:
```csharp
// Good
Task<string> GetSha1(string owner, string name, string reference);
// Not
Task<string> Sha1(string owner, string name, string reference);
```

3. **Always use nameof() for parameter validation** instead of string literals:
```csharp
// Good
Ensure.ArgumentNotNull(client, nameof(client));
// Not
Ensure.ArgumentNotNull(client, "client");
```

4. **Use descriptive parameter names** that clearly communicate purpose:
```csharp
// Good - clear distinction between concepts
IObservable<Unit> Delete(string owner, string name, int number, int reactionId);
// Not - ambiguous
IObservable<Unit> Delete(string owner, string name, int number, int reaction);

// Good - clearly identifies repository ID
Task<Repository> Transfer(long repositoryId, RepositoryTransfer transfer);
// Not - too generic
Task<Repository> Transfer(long id, RepositoryTransfer transfer);
```

5. **For pull request operations, use 'number'** instead of 'id' to avoid confusion with the internal ID:
```csharp
// Good
IObservable<PullRequest> Get(string owner, string name, int number);
// Not
IObservable<PullRequest> Get(string owner, string name, int pullRequestId);
```

These conventions help maintain a consistent codebase, reduce confusion, and make the API more intuitive for consumers.

---

## Use specific assertions

<!-- source: octokit/octokit.net | topic: Testing | language: C# | updated: 2018-06-20 -->

Always write assertions that verify specific, expected values rather than simple existence or boolean checks. This ensures tests validate exactly what you intend and provides clearer error messages when tests fail.

**Do this:**
```csharp
// Use Assert.Equal to get both values when the test fails
Assert.Equal(2, issue.Assignees.Count);
Assert.Equal(_context.RepositoryOwner, closed.Assignees[0].Login);
```

**Not this:**
```csharp
// Provides less helpful error messages
Assert.True(issue.Assignees.Count == 2);
Assert.True(closed.Assignees[0].Login == _context.RepositoryOwner);
```

When testing state changes, verify the specific new values rather than just checking the count:
```csharp
// Verify the specific team that should be present after a change
Assert.Contains(restrictions, team => team.Name == contextOrgTeam2.TeamName);
// Rather than just checking the count which could be correct by coincidence
Assert.Equal(1, restrictions.Count);
```

In method tests, assert on exact return values, not just that a method was called. For object state assertions, verify the fields that should have changed rather than just checking if an object is non-null.

By being specific in your assertions, you:
1. Create tests that clearly document expectations
2. Get more helpful error messages showing both expected and actual values
3. Avoid false positives where tests pass despite functional failures
4. Make it easier to diagnose failures when tests eventually break

---

## Abstract configuration access

<!-- source: octokit/octokit.net | topic: Configurations | language: C# | updated: 2016-12-23 -->

Use abstraction layers to access configuration settings rather than accessing environment variables, feature flags, or other configuration sources directly. This improves maintainability by centralizing configuration logic, enabling validation, and simplifying testing.

**Why it matters:**
- Centralizes configuration management in a single location
- Enables validation of configuration values
- Makes it easier to mock configuration in tests
- Provides a clean API for configuration consumers

**Implementation:**

Instead of:
```csharp
var organization = Environment.GetEnvironmentVariable("OCTOKIT_GITHUBORGANIZATION");
```

Prefer:
```csharp
var organization = Helper.Organization; // Abstracted access to environment variable
```

For environment-specific code, use consistent preprocessor directives and centralize format strings:
```csharp
var format = 
#if !HAS_ENVIRONMENT
    "{0} ({1}; {2}; {3}; Octokit {4})";
#else
    "{0} ({1} {2}; {3}; {4}; Octokit {5})";
#endif

// Use format variable instead of duplicating the format string
```

When creating clients that require specific configuration constraints:
```csharp
public EnterpriseSpecificClient(IApiConnection apiConnection)
{
    // Validate configuration constraints early
    if (!IsEnterpriseUrl(apiConnection.Connection.BaseUrl))
    {
        throw new InvalidOperationException(
            "This client only works with GitHub Enterprise URLs.");
    }
    
    // Rest of constructor...
}
```

---

## Precise and consistent naming

<!-- source: octokit/octokit.net | topic: Naming Conventions | language: Other | updated: 2015-10-16 -->

Names should clearly indicate their specific purpose and context, while maintaining correct capitalization of brand names and products. 

When naming variables, parameters, or targets:
1. Choose names that specifically describe their purpose and domain context
2. Use proper capitalization for brand names and products
3. Ensure names accurately represent their intended function

**Examples:**
- Use `GITHUBOWNER` instead of `GITOWNER` when specifically referring to GitHub operations
- Write `GitHub` not `Github` to maintain correct brand capitalization

This practice improves code clarity, reduces confusion about a variable's intended use, and presents a professional attention to detail in your codebase.