diff --git a/README.instructions.md b/README.instructions.md index a3fb7d6..0ac8ad5 100644 --- a/README.instructions.md +++ b/README.instructions.md @@ -91,4 +91,5 @@ Team and project-specific instructions to enhance GitHub Copilot's behavior for | [TaskSync V4 Protocol](instructions/tasksync.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftasksync.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftasksync.instructions.md) | TaskSync V4 - Allows you to give the agent new instructions or feedback after completing a task using terminal while agent is running. | | [Azure Terraform Best Practices](instructions/terraform-azure.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fterraform-azure.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fterraform-azure.instructions.md) | Create or modify solutions built using Terraform on Azure. | | [Terraform Conventions](instructions/terraform.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fterraform.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fterraform.instructions.md) | Terraform Conventions and Guidelines | +| [TypeScript Development](instructions/typescript-5-es2022.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftypescript-5-es2022.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ftypescript-5-es2022.instructions.md) | Guidelines for TypeScript Development targeting TypeScript 5.x and ES2022 output | | [VueJS 3 Development Instructions](instructions/vuejs3.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fvuejs3.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fvuejs3.instructions.md) | VueJS 3 development standards and best practices with Composition API and TypeScript | diff --git a/instructions/typescript-5-es2022.instructions.md b/instructions/typescript-5-es2022.instructions.md new file mode 100644 index 0000000..1b53035 --- /dev/null +++ b/instructions/typescript-5-es2022.instructions.md @@ -0,0 +1,114 @@ +--- +description: 'Guidelines for TypeScript Development targeting TypeScript 5.x and ES2022 output' +applyTo: '**/*.ts' +--- + +# TypeScript Development + +> These instructions assume projects are built with TypeScript 5.x (or newer) compiling to an ES2022 JavaScript baseline. Adjust guidance if your runtime requires older language targets or down-level transpilation. + +## Core Intent + +- Respect the existing architecture and coding standards. +- Prefer readable, explicit solutions over clever shortcuts. +- Extend current abstractions before inventing new ones. +- Prioritize maintainability and clarity, short methods and classes, clean code. + +## General Guardrails + +- Target TypeScript 5.x / ES2022 and prefer native features over polyfills. +- Use pure ES modules; never emit `require`, `module.exports`, or CommonJS helpers. +- Rely on the project's build, lint, and test scripts unless asked otherwise. +- Note design trade-offs when intent is not obvious. + +## Project Organization + +- Follow the repository's folder and responsibility layout for new code. +- Use kebab-case filenames (e.g., `user-session.ts`, `data-service.ts`) unless told otherwise. +- Keep tests, types, and helpers near their implementation when it aids discovery. +- Reuse or extend shared utilities before adding new ones. + +## Naming & Style + +- Use PascalCase for classes, interfaces, enums, and type aliases; camelCase for everything else. +- Skip interface prefixes like `I`; rely on descriptive names. +- Name things for their behavior or domain meaning, not implementation. + +## Formatting & Style + +- Run the repository's lint/format scripts (e.g., `npm run lint`) before submitting. +- Match the project's indentation, quote style, and trailing comma rules. +- Keep functions focused; extract helpers when logic branches grow. +- Favor immutable data and pure functions when practical. + +## Type System Expectations + +- Avoid `any` (implicit or explicit); prefer `unknown` plus narrowing. +- Use discriminated unions for realtime events and state machines. +- Centralize shared contracts instead of duplicating shapes. +- Express intent with TypeScript utility types (e.g., `Readonly`, `Partial`, `Record`). + +## Async, Events & Error Handling + +- Use `async/await`; wrap awaits in try/catch with structured errors. +- Guard edge cases early to avoid deep nesting. +- Send errors through the project's logging/telemetry utilities. +- Surface user-facing errors via the repository's notification pattern. +- Debounce configuration-driven updates and dispose resources deterministically. + +## Architecture & Patterns + +- Follow the repository's dependency injection or composition pattern; keep modules single-purpose. +- Observe existing initialization and disposal sequences when wiring into lifecycles. +- Keep transport, domain, and presentation layers decoupled with clear interfaces. +- Supply lifecycle hooks (e.g., `initialize`, `dispose`) and targeted tests when adding services. + +## External Integrations + +- Instantiate clients outside hot paths and inject them for testability. +- Never hardcode secrets; load them from secure sources. +- Apply retries, backoff, and cancellation to network or IO calls. +- Normalize external responses and map errors to domain shapes. + +## Security Practices + +- Validate and sanitize external input with schema validators or type guards. +- Avoid dynamic code execution and untrusted template rendering. +- Encode untrusted content before rendering HTML; use framework escaping or trusted types. +- Use parameterized queries or prepared statements to block injection. +- Keep secrets in secure storage, rotate them regularly, and request least-privilege scopes. +- Favor immutable flows and defensive copies for sensitive data. +- Use vetted crypto libraries only. +- Patch dependencies promptly and monitor advisories. + +## Configuration & Secrets + +- Reach configuration through shared helpers and validate with schemas or dedicated validators. +- Handle secrets via the project's secure storage; guard `undefined` and error states. +- Document new configuration keys and update related tests. + +## UI & UX Components + +- Sanitize user or external content before rendering. +- Keep UI layers thin; push heavy logic to services or state managers. +- Use messaging or events to decouple UI from business logic. + +## Testing Expectations + +- Add or update unit tests with the project's framework and naming style. +- Expand integration or end-to-end suites when behavior crosses modules or platform APIs. +- Run targeted test scripts for quick feedback before submitting. +- Avoid brittle timing assertions; prefer fake timers or injected clocks. + +## Performance & Reliability + +- Lazy-load heavy dependencies and dispose them when done. +- Defer expensive work until users need it. +- Batch or debounce high-frequency events to reduce thrash. +- Track resource lifetimes to prevent leaks. + +## Documentation & Comments + +- Add JSDoc to public APIs; include `@remarks` or `@example` when helpful. +- Write comments that capture intent, and remove stale notes during refactors. +- Update architecture or design docs when introducing significant patterns.