first commit

docs/foundation/data/templates/src/errors/error-codes.md

@@ -0,0 +1,69 @@
+# error-codes
+
+## Purpose
+
+Defines and freezes the complete error-code registry for `@suaveplan/templates` using the `defineCodes` utility from `@suaveplan/error`. Every error thrown by the template engine carries one of these stable codes, enabling consumer code to programmatically inspect and react to error conditions without relying on string matching against human-readable messages. The `TEMPLATE.` namespace prefix ensures global uniqueness across the project.
+
+## Features
+
+- Seven stable error codes prefixed with `TEMPLATE.`.
+- Codes are frozen at module load time — `defineCodes` returns a `Readonly` object so no code can be modified or added after import.
+- The `TemplateCode` union type is derived from the registry using `typeof TEMPLATE_CODES`, so adding a new code automatically extends the type.
+- Used by `TemplateError`, `PluginError`, and `MaxDepthError` constructors to tag every thrown error.
+
+## Usage: Basic Example
+
+```ts
+import { TEMPLATE_CODES } from "@suaveplan/templates/errors/error-codes";
+
+try {
+    engine.parse("{missing}", {});
+} catch (err) {
+    if (err instanceof TemplateError && err.code === TEMPLATE_CODES.MISSING_VARIABLE) {
+        console.log("Missing variable:", err.renderContext);
+    }
+}
+```
+
+## Usage: Advanced Example
+
+```ts
+import { TEMPLATE_CODES } from "@suaveplan/templates/errors/error-codes";
+import type { TemplateCode } from "@suaveplan/templates/errors/error-codes";
+
+function isTemplateError(code: TemplateCode): boolean {
+    return Object.values(TEMPLATE_CODES).includes(code);
+}
+
+// Inspect the full registry programmatically
+console.log(Object.keys(TEMPLATE_CODES));
+// → ["PARSE_ERROR", "MISSING_VARIABLE", "PLUGIN_CONFLICT", "PLUGIN_ERROR", "RENDER_ERROR", "MAX_DEPTH", "INVALID_CONFIG"]
+```
+
+## API Reference
+
+### `TEMPLATE_CODES`
+
+A frozen `Record<string, string>` with the following keys:
+
+| Key | Value | Thrown by |
+|-----|-------|-----------|
+| `PARSE_ERROR` | `"TEMPLATE.PARSE_ERROR"` | Engine catch-all for unexpected parse failures |
+| `MISSING_VARIABLE` | `"TEMPLATE.MISSING_VARIABLE"` | When `throwOnError` is set and a variable is absent |
+| `PLUGIN_CONFLICT` | `"TEMPLATE.PLUGIN_CONFLICT"` | `engine.use()` with a duplicate plugin name |
+| `PLUGIN_ERROR` | `"TEMPLATE.PLUGIN_ERROR"` | When a plugin's `transform()` throws unexpectedly |
+| `RENDER_ERROR` | `"TEMPLATE.RENDER_ERROR"` | General render pipeline failure |
+| `MAX_DEPTH` | `"TEMPLATE.MAX_DEPTH"` | Recursive render depth exceeds `maxDepth` |
+| `INVALID_CONFIG` | `"TEMPLATE.INVALID_CONFIG"` | Invalid engine construction options |
+
+### `TemplateCode`
+
+`type TemplateCode = (typeof TEMPLATE_CODES)[keyof typeof TEMPLATE_CODES]`
+
+Union of all string literal values in `TEMPLATE_CODES`. Used as the generic type parameter for `TemplateError`, `PluginError`, and `MaxDepthError` to enforce that every error carries a known code.
+
+## Implementation Notes
+
+- `defineCodes("TEMPLATE", [...])` from `@suaveplan/error` constructs the registry by prefixing each code name with `"TEMPLATE."` and freezing the result with `Object.freeze`. This prevents accidental mutation in consumer code.
+- The registry is exported as a named constant rather than individual string literals to prevent typo-based drift between the registered codes and their usage sites; all usages should reference `TEMPLATE_CODES.SOME_CODE` rather than string literals.
+- The `as const` assertion on the code-name array is required so TypeScript infers a tuple of string literals rather than `string[]`, enabling precise inference of `TemplateCode`.