chore(engine): implement UT & copilot instructions (#23)

Author: fraxken

.github/copilot-instructions.md

@@ -0,0 +1,74 @@
+---
+applyTo: "**/*.js, **/*.mjs, **/*.cjs"
+---
+
+# Coding Standards for This Project
+
+## 1  Language & Runtime
+
+* Write all source files in **modern JavaScript (ECMAScript 2024)**.
+* Target **Node.js 22 or newer** and use native **ESM** syntax (`import`/`export`).
+
+## 2  General Style
+
+* Prefer **clarity over cleverness**; strive for readable, maintainable code.
+* Always use **async/await** for asynchronous operations.
+  * When converting callback APIs, use `node:util` → `promisify`.
+* **Strings:** use **double quotes** (`"…"`) or **template literals** (\`…\`); never single quotes.
+* **Semicolons:** terminate *every* statement with `;`.
+* **Equality:** use strict operators `===` / `!==`; never `==` / `!=`.
+* **Variables:**
+  * `const` for bindings that never change,
+  * `let` for re‑assignable bindings.
+* **Loops:** use `for…of` for arrays/iterables; use `for…in` only for object keys when truly needed.
+* **Arrow functions:** **always** wrap parameters in parentheses—even a single parameter.
+* **Conditionals & loops:** wrap condition expressions in parentheses.
+* No inline end‑of‑line comments; place comments on the **preceding line**.
+  Keep comments concise; code should be self‑explanatory.
+* Respect **.editorconfig** rules (indentation, line endings, etc.).
+* Favor a **functional style** (pure functions, immutability) when practical.
+* Before adding any external dependency, **ask the user** for approval.
+
+## 3  Imports
+
+```js
+// Import Node.js Dependencies
+import fs from "node:fs/promises";
+import path from "node:path";
+
+// Import Third‑party Dependencies
+import express from "express";
+
+// Import Internal Dependencies
+import { doSomething } from "./lib/do‑something.js";
+```
+
+* Order **exactly** as shown: Node.js core → Third‑party → Internal.
+* Precede each block with the indicated comment.
+* Use **`node:`** prefix for Node.js core modules (e.g., `import fs from "node:fs"`).
+* Use **`import`** syntax for all imports; never `require()`.
+
+## 4  Naming
+
+| Kind                              | Convention       | Example                 |
+| --------------------------------- | ---------------- | ----------------------- |
+| Classes, Interfaces, Type Aliases | **PascalCase**   | `class HttpServer {}`   |
+| Variables, Functions, Methods     | **camelCase**    | `const fetchData = …`   |
+| Private class fields & methods    | `#` prefix       | `#connectionPool`       |
+| Exported constants                | **ALL\_CAPS**    | `export const API_URL`  |
+| File‑local constants              | `k` + PascalCase | `const kTimeoutMs = 30` |
+
+Place all constants directly **beneath the imports** under a `// CONSTANTS` comment.
+
+## 5  Testing
+
+* Use Node.js **core test runner** `node:test`.
+* Use **`node:assert`** for assertions.
+* Cover edge cases and error handling.
+* **Never** modify production code solely to ease testing.
+* For browser‑like APIs, mock the DOM with **`happy-dom`**.
+
+## 6  User Interaction (for Copilot / LLM)
+
+* When the spec is ambiguous, **ask clarifying questions**.
+* Reply in the **same language** as the prompt; generate **English** for code, comments, and docs.

.github/markdown.instructions.md

@@ -0,0 +1,38 @@
+---
+description: 'Documentation and content creation standards'
+applyTo: '**/*.md'
+---
+
+## Markdown Content Rules
+
+The following markdown content rules are enforced in the validators:
+
+1. **Headings**: Use appropriate heading levels (H2, H3, etc.) to structure your content. Do not use an H1 heading, as this will be generated based on the title.
+2. **Lists**: Use bullet points or numbered lists for lists. Ensure proper indentation and spacing.
+3. **Code Blocks**: Use fenced code blocks for code snippets. Specify the language for syntax highlighting.
+4. **Links**: Use proper markdown syntax for links. Ensure that links are valid and accessible.
+5. **Images**: Use proper markdown syntax for images. Include alt text for accessibility.
+6. **Tables**: Use markdown tables for tabular data. Ensure proper formatting and alignment.
+7. **Line Length**: Limit line length to 400 characters for readability.
+8. **Whitespace**: Use appropriate whitespace to separate sections and improve readability.
+
+## Formatting and Structure
+
+Follow these guidelines for formatting and structuring your markdown content:
+
+- **Headings**: Use `##` for H2 and `###` for H3. Ensure that headings are used in a hierarchical manner. Recommend restructuring if content includes H4, and more strongly recommend for H5.
+- **Lists**: Use `-` for bullet points and `1.` for numbered lists. Indent nested lists with two spaces.
+- **Code Blocks**: Use triple backticks (`) to create fenced code blocks. Specify the language after the opening backticks for syntax highlighting (e.g., `csharp).
+- **Links**: Use `[link text](URL)` for links. Ensure that the link text is descriptive and the URL is valid.
+- **Images**: Use `![alt text](image URL)` for images. Include a brief description of the image in the alt text.
+- **Tables**: Use `|` to create tables. Ensure that columns are properly aligned and headers are included.
+- **Line Length**: Break lines at 80 characters to improve readability. Use soft line breaks for long paragraphs.
+- **Whitespace**: Use blank lines to separate sections and improve readability. Avoid excessive whitespace.
+
+## Validation Requirements
+
+Ensure compliance with the following validation requirements:
+
+- **Content Rules**: Ensure that the content follows the markdown content rules specified above.
+- **Formatting**: Ensure that the content is properly formatted and structured according to the guidelines.
+- **Validation**: Run the validation tools to check for compliance with the rules and guidelines.

.github/typescript.instructions.md

@@ -0,0 +1,100 @@
+---
+applyTo: "**/*.ts, **/*.mts, **/*.cts"
+---
+
+# TypeScript Coding Standards for This Project
+
+These guidelines complement the existing **JavaScript** rules and are **binding** for all TypeScript source files.
+
+---
+
+## 1  Compiler Baseline (`tsconfig.json`)
+
+The project’s `tsconfig.json` is **authoritative**. Do **not** change it.
+
+```json
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "NodeNext",
+    "esModuleInterop": true,
+    "allowJs": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+
+    "strict": true,
+    "strictNullChecks": true,
+    "noImplicitOverride": true,
+    "noImplicitThis": true,
+    "noImplicitReturns": true,
+    "noUnusedLocals": true,
+
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+    "experimentalDecorators": true,
+    "lib": ["es2022"]
+  }
+}
+```
+
+Key implications:
+
+* **ESM only** (`module: "NodeNext"`, `verbatimModuleSyntax: true`).  Use `import`/`export`, never CommonJS `require`.
+* **Target ES2022** → you may use class fields, `at()` on arrays, `Error.cause`, `RegExp matchIndices`, etc.
+* **`strict` mode** with additional checks: treat all compile‑time warnings as **errors**.
+* **`allowJs`: true** means you *may* import legacy `.js` files; new code **must** be `.ts`/`.tsx`.
+* **Decorators** are enabled (`experimentalDecorators`). Use them sparingly and document intent.
+
+---
+
+## 2  General Style
+
+(The JavaScript standards apply; this section covers TS‑specifics.)
+
+| Topic                       | Rule                                                                                                                                                     |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Types vs Interfaces**     | Prefer **`type` aliases** for unions, mapped & conditional types. <br>Use **`interface`** for plain object shapes intended for extension.                 |
+| **Explicit typing**         | Always annotate **public APIs** (exported functions, class members, constants) with explicit types.<br>Local variables may rely on inference if trivial. |
+| **`any` / `unknown`**       | `any` is allowed by config but **should be avoided**; use `unknown` with proper narrowing.                                                               |
+| **Nullish values**          | Handle `null` / `undefined` explicitly (`strictNullChecks`). Use the *nullish coalescing* operator (`??`) or early returns.                              |
+| **Enums**                   | Avoid `enum`; prefer `as const` objects or union literal types for safer exhaustiveness.                                                                 |
+| **Tuples & readonly**       | Mark tuples as `readonly` when contents shouldn’t mutate (`readonly [T1, T2]`).                                                                          |
+| **Generics**                | Provide descriptive parameter names (`TData`, `TError`). Supply default type parameters when helpful.                                                    |
+| **Decorators**              | Keep decorator logic *pure*; avoid hidden side‑effects. Document with JSDoc above the decorator.                                                         |
+| **Assertions & type casts** | Prefer `as` casting; avoid the angle‑bracket form. Keep casts to the narrowest scope possible.                                                           |
+| **Error handling**          | Use custom `class`es extending `Error` with a descriptive **PascalCase** name and optional `cause`.                                                      |
+
+---
+
+## 3  Imports & Module Resolution
+
+1. **Order** exactly as in the JavaScript guide: core → third‑party → internal.
+   Always include file extensions (e.g. `"./util.js"`).
+2. **JSON modules** can be imported directly (`resolveJsonModule: true`).
+
+   ```ts
+   import packageJson from "../package.json" assert { type: "json" };
+   ```
+3. **Type‑only imports**: use the `import type { … } from "…";` form to avoid runtime overhead.
+4. Keep each import statement **on its own line**.
+
+---
+
+## 4  Naming Conventions
+
+Follow the same table as the JavaScript guide, with additions:
+
+* **Type parameters**: `T`, `TValue`, `TOptions` (PascalCase prefixed with `T`).
+* **Namespace imports** (rare): camelCase (e.g. `import * as fs from "node:fs/promises";`).
+
+---
+
+## 5  Testing
+
+* Write tests in **TypeScript** (preferred extension `.spec.ts`).
+* Use **Node.js core test runner** (`node:test`). Configure the runner to load `tsx` or `ts-node/register` for runtime transpilation.