agentharness: Instructions file for GitHub Copilot

Generated from languages/typescript/CONVENTIONS.md by tools/generate-copilot-instructions.sh (https://github.com/andr-ca/agentharness) — do not hand-edit; regenerate instead. Only applied by Copilot when editing a file matching *.ts,*.tsx.

---

TypeScript Conventions & Best Practices

Naming (camelCase functions/variables, PascalCase classes/types, UPPER_SNAKE_CASE module constants), import grouping (external → internal → types), and generics (T/U for simple cases, descriptive names for complex ones) follow standard TypeScript/JS convention — see the TypeScript Handbook and Google's TypeScript Style Guide for the parts not worth restating here. Below are the places this repo makes an actual decision among genuinely competing options.

Private Members: # vs. _prefix

Prefer native # private fields (ES2022+/TS 3.8+) in new code — real runtime privacy, not just erased at compile time and still reachable via a cast or ["_name"]. A leading underscore (_name) is an older convention, not a deprecated language feature: it's still common in code that predates # fields, and isn't something to rewrite on sight.

class User {
  #internalState: Map<string, unknown>;   // true runtime privacy
  #validate(): boolean { /* ... */ }
}

Null vs. Undefined

TypeScript's own idioms don't universally favor one over the other, and neither should this guide — optional properties (?), optional parameters, and destructuring defaults all naturally produce undefined, not null. Pick based on what the absence means, not by habit:

• undefined (via ?) for "not provided / not yet set" — the language's own default for anything optional.
• null for an explicit, deliberate "no value" the code sets on purpose (a nullable database column, "user cleared this field").
• Whichever you pick for a given API, apply it consistently — the bug is mixing both for the same kind of absence within one module, not the specific choice.