# Error Codes

## Error Code Reference

Error codes follow a prefixed numbering scheme. The prefix encodes the category and severity.

### General Errors (E0xxx)

| Code | Constant | Description | Triggered By |
|------|----------|-------------|-------------|
| `E0001` | `ErrUnexpectedToken` | Unexpected or unrecognizable character | Tokenizer encounter of non-ASCII, non-operator char |
| `E0002` | `ErrUnclosedString` | Unclosed string literal | Missing closing quote at EOF |
| `E0003` | `ErrUnclosedComment` | Unclosed block comment | Missing `*/`, `]#`, `#}` etc. at EOF |
| `E0004` | `ErrUnclosedBlock` | Unclosed block/control structure | Language-specific: unclosed `if`/`for`/`class`/etc. |
| `E0005` | `ErrMismatchedBracket` | Mismatched or unexpected closing bracket | `)` without `(`, `</div>` without `<div>` |
| `E0006` | `ErrUnclosedBracket` | Unclosed bracket at EOF | `validateBrackets()` finds remaining items on bracket stack |
| `E0007` | `ErrInvalidSyntax` | General invalid syntax | JSON parse error, TOML missing `=`, YAML empty key |
| `E0008` | `ErrUnexpectedEOF` | Unexpected end of file | Reserved for incomplete constructs not covered by other codes |
| `E0009` | `ErrEmptySource` | Source is empty (zero-length string) | `validate()` with `source.len == 0` |
| `E0010` | `ErrEncodingError` | Encoding error | Reserved for non-UTF-8 input |
| `E0011` | -- | File not found | `validateFile()` with non-existent path |

### Language-Specific Errors (E1xxx)

| Code | Constant | Description | Languages |
|------|----------|-------------|-----------|
| `E1001` | `ErrUnexpectedIndent` | Unexpected or inconsistent indentation | Python |
| `E1002` | `ErrMissingIndent` | Missing indentation after block opener | Python |
| `E1003` | `ErrDuplicateParam` | Duplicate parameter name | (reserved) |
| `E1004` | `ErrUndefinedVariable` | Reference to undefined variable | (reserved) |
| `E1005` | `ErrTypeMismatch` | Type mismatch | (reserved) |
| `E1006` | `ErrInvalidAssignment` | Invalid assignment target | (reserved) |
| `E1007` | `ErrMissingReturn` | Function missing return statement | (reserved) |
| `E1008` | `ErrInvalidDecorator` | Invalid decorator usage | Python |
| `E1009` | `ErrInvalidImport` | Invalid import statement | (reserved) |

### Template Errors (E2xxx)

| Code | Constant | Description | Languages |
|------|----------|-------------|-----------|
| `E2001` | `ErrUnclosedTemplateTag` | Unclosed template expression/block tag | Jinja |
| `E2002` | `ErrUnclosedBlockTag` | Unclosed block tag with no matching end tag | Jinja |
| `E2003` | `ErrInvalidFilter` | Invalid filter in template expression | Jinja |

### Info Codes (I0xxx)

| Code | Constant | Description |
|------|----------|-------------|
| `I0001` | `InfoLongLine` | Line exceeds recommended length |
| `I0002` | `InfoTrailingWhitespace` | Trailing whitespace detected |

### Warning Codes (W0xxx / W1xxx)

| Code | Constant | Description |
|------|----------|-------------|
| `W0001` | `WarnUnusedVariable` | Variable declared but never used |
| `W0002` | `WarnInconsistentNaming` | Naming convention inconsistency |
| `W0003` | `WarnMissingDoc` | Public symbol missing documentation |
| `W1001` | -- | Tab characters in YAML indentation |

### Internal Error

| Code | Description | Triggered By |
|------|-------------|-------------|
| `E9999` | Internal framework error (never-crash fallback) | Any unhandled `Exception` in `validate()` or `validateSource()` |

---

## IO Table: Supported Languages and Per-Language Errors

### Input/Output Contract

Every validation function follows the same contract:

| Input | Output |
|-------|--------|
| `source: string` (required) | `ValidationResult` with `valid: bool` |
| `flavor: LanguageFlavor = lfUnknown` | `ValidationResult.errors: seq[ValidationError]` |
| `options: ValidationOptions` (optional) | `ValidationResult.moduleInfo: ModuleInfo` |
| `sourcePath: string = ""` (optional) | `ValidationResult.durationMs: float` |

**Guarantees**:
- Never throws - all exceptions are caught and returned as `E9999` errors
- Empty source returns `E0009` (or `valid: true` for YAML/TOML where empty is valid)
- File not found returns `E0011`
- Unknown flavor with no detection possible returns an `E0007` error
- Every error has a `code`, `message`, `severity`, `position`, and optional `hint`

### Per-Language Tokenizer, Validator, and Error Table

#### Nim (`.nim`, `.nims`, `.nimble`)

| Aspect | Details |
|--------|---------|
| Tokenizer | `nim_tokenizer.nim` - `NimTokenizer` |
| Validator | `nim_validator.nim` - `NimValidator` |
| Keywords | 80+ (addr, and, as, block, break, case, const, converter, defer, discard, elif, else, enum, except, export, finally, for, from, func, if, import, in, include, iterator, let, macro, method, mixin, mod, nil, not, object, of, or, proc, ptr, raise, ref, return, template, try, tuple, type, using, var, when, while, with, yield, etc.) |

| Error Code | Condition | Severity | Hint |
|------------|-----------|----------|------|
| `E0001` | Unexpected character (non-ASCII, unrecognizable) | `esWarning` | Shows hex `U+XXXX` value |
| `E0002` | Unclosed string (`"..."` at EOF) | `esError` | "Add a closing quote" |
| `E0002` | Unclosed multi-line string (`"""` at EOF) | `esError` | -- |
| `E0002` | Newline inside string literal | `esError` | -- |
| `E0002` | Unclosed raw string (`r"..."` at EOF) | `esError` | -- |
| `E0002` | Unclosed character literal (`'x` at EOF) | `esError` | -- |
| `E0003` | Unclosed block comment (`#[` without `]#`) | `esError` | "Add closing `]#`" |
| `E0006` | Unclosed bracket (`(`, `[`, `{` at EOF) | `esError` | "Add matching closing bracket" |

Structural extraction: imports (`from X import Y`), functions (`proc`, `func`, `method`, `template`, `macro`, `iterator`, `converter`), types (`type Foo`).

#### Bash / Shell (`.sh`, `.bash`, `.zsh`, `.fish`)

| Aspect | Details |
|--------|---------|
| Tokenizer | `bash_tokenizer.nim` - `BashTokenizer` |
| Validator | `bash_validator.nim` - `BashValidator` |
| Keywords | 38+ (if, then, else, elif, fi, case, esac, for, while, until, do, done, in, function, select, time, return, break, continue, exit, declare, local, export, readonly, unset, eval, exec, let, source, shift, trap, type, typeset, ulimit, umask, alias, read, echo) |

| Error Code | Condition | Severity | Hint |
|------------|-----------|----------|------|
| `E0002` | Unclosed single-quoted string | `esError` | -- |
| `E0002` | Unclosed double-quoted string | `esError` | -- |
| `E0004` | Unclosed `${var}` expansion | `esError` | -- |
| `E0004` | Unclosed `$()` command substitution | `esError` | -- |
| `E0004` | Unclosed `if` block (`if` without matching `fi`) | `esError` | "Add missing 'fi'" |
| `E0004` | Unclosed loop (`for`/`while`/`until` without `done`) | `esError` | "Add missing 'done'" |
| `E0004` | Unclosed `case` block (`case` without `esac`) | `esError` | "Add missing 'esac'" |
| `E0006` | Unclosed bracket (`(`, `[`, `{` at EOF) | `esError` | -- |

Special features: shebang detection (`#!`), heredoc detection (`<<EOF`), variable expansion (`$var`, `${var}`), backtick command substitution, arithmetic expansion (`(( ))`).

#### Python (`.py`, `.pyw`, `.pyx`, `.pxd`)

| Aspect | Details |
|--------|---------|
| Tokenizer | `python_tokenizer.nim` - `PythonTokenizer` |
| Validator | `python_validator.nim` - `PythonValidator` |
| Keywords | 33 (False, None, True, and, as, assert, async, await, break, class, continue, def, del, elif, else, except, finally, for, from, global, if, import, in, is, lambda, nonlocal, not, or, pass, raise, return, try, while, with, yield) |

| Error Code | Condition | Severity | Hint |
|------------|-----------|----------|------|
| `E0002` | Unclosed string (`"..."` or `'...'` at EOF) | `esError` | -- |
| `E0002` | Unclosed triple-quoted string (`"""` or `'''` at EOF) | `esError` | -- |
| `E0002` | Unclosed f-string (`f"..."` at EOF) | `esError` | -- |
| `E0002` | Newline inside string literal | `esError` | -- |
| `E1001` | Indentation mismatch at block boundary | `esError` | -- |
| `E0006` | Unclosed bracket (`(`, `[`, `{` at EOF) | `esError` | -- |

Special features: f-string interpolation with nested braces, indentation tracking (INDENT/DEDENT tokens), decorator detection (`@`), line continuation (`\`).

Structural extraction: imports (`import X`, `from X import Y`), functions (`def`), classes (`class`).

#### JavaScript / TypeScript (`.js`, `.mjs`, `.cjs`, `.ts`, `.tsx`)

| Aspect | Details |
|--------|---------|
| Tokenizer | `javascript_tokenizer.nim` - `JavaScriptTokenizer` |
| Validator | `javascript_validator.nim` - `JavaScriptValidator` |
| Keywords | 60+ (async, await, break, case, catch, class, const, continue, debugger, default, delete, do, else, export, extends, false, finally, for, function, if, import, in, instanceof, let, new, null, of, return, super, switch, static, this, throw, true, try, typeof, var, void, while, with, yield + TypeScript: interface, type, declare, module, namespace, abstract, readonly, as, any, boolean, number, string, never, keyof, infer, unknown) |

| Error Code | Condition | Severity | Hint |
|------------|-----------|----------|------|
| `E0002` | Unclosed string (`"..."` or `'...'` at EOF) | `esError` | -- |
| `E0002` | Unclosed template literal (`` `...` `` at EOF) | `esError` | -- |
| `E0002` | Newline inside string literal | `esError` | -- |
| `E0006` | Unclosed bracket (`(`, `[`, `{` at EOF) | `esError` | -- |

Special features: template literals with `${}` interpolation nesting, regex literal detection, arrow function detection (`=>`), ESM import/export.

Structural extraction: imports/exports, functions (`function`, `async`), classes.

#### PHP (`.php`, `.phtml`)

| Aspect | Details |
|--------|---------|
| Tokenizer | `php_tokenizer.nim` - `PHPTokenizer` |
| Validator | `php_validator.nim` - `PHPValidator` |
| Mode switching | Tracks `inPhpMode` flag - toggles on `<?php`/`<?` and `?>` |

| Error Code | Condition | Severity | Hint |
|------------|-----------|----------|------|
| `E0002` | Unclosed string | `esError` | -- |
| `E0006` | Unclosed bracket (`(`, `[`, `{` at EOF) | `esError` | -- |

Special features: PHP/HTML mode switching, `<?php`, `<?=`, `?>` detection, variable names (`$var`, `$obj->prop`).

Structural extraction: functions (`function`, `fn`), classes (`class`), imports/requires (`include`, `require`, `use`, `namespace`).

#### HTML / XML (`.html`, `.htm`, `.xhtml`, `.xml`, `.svg`)

| Aspect | Details |
|--------|---------|
| Tokenizer | `html_tokenizer.nim` - `HTMLTokenizer` |
| Validator | `html_validator.nim` - `HTMLValidator` |
| Void elements | 14: area, base, br, col, embed, hr, img, input, link, meta, param, source, track, wbr |

| Error Code | Condition | Severity | Hint |
|------------|-----------|----------|------|
| `E0003` | Unclosed HTML comment (`<!--` without `-->`) | `esError` | -- |
| `E0004` | Unclosed HTML tag (e.g., `<div>` without `</div>`) | `esError` | "Add closing `</tagname>`" |
| `E0005` | Unexpected closing tag (mismatched nesting) | `esWarning` | "Check that tags are properly nested" |

Special features: tag stack balancing, void element awareness (no closing tag needed for self-closing elements), attribute parsing with quoted values, `<!DOCTYPE>`, `<?xml?>` directives.

#### Jinja2 (`.jinja`, `.jinja2`, `.j2`, `.html.j2`)

| Aspect | Details |
|--------|---------|
| Tokenizer | `jinja_tokenizer.nim` - `JinjaTokenizer` |
| Validator | `jinja_validator.nim` - `JinjaValidator` |

| Error Code | Condition | Severity | Hint |
|------------|-----------|----------|------|
| `E0003` | Unclosed Jinja comment (`{#` without `#}`) | `esError` | -- |
| `E2001` | Unclosed expression tag (`{{` without `}}`) | Implicit via tokenizer | -- |
| `E2001` | Unclosed block tag (`{%` without `%}`) | Implicit via tokenizer | -- |
| `E2002` | Unclosed `for` block (no matching `endfor`) | `esError` | "Add `{% endfor %}`" |
| `E2002` | Unclosed `if` block (no matching `endif`) | `esError` | "Add `{% endif %}`" |
| `E2002` | Unclosed `block` (no matching `endblock`) | `esError` | "Add `{% endblock %}`" |
| `E2002` | Unclosed `macro`, `filter`, `raw`, `autoescape`, `call`, `with` | `esError` | "Add matching `end{tag}`" |

Special features: tracks 12 block tag types (`for`, `if`, `block`, `macro`, `filter`, `raw`, `autoescape`, `call`, `with`), validates matching end tags, handles content between template syntax and plain text.

#### JSON (`.json`, `.jsonc`)

| Aspect | Details |
|--------|---------|
| Validator | `config_validators.nim` - `JSONValidator` |
| Method | Uses Nim's built-in `parseJson()` for full validation |

| Error Code | Condition | Severity | Hint |
|------------|-----------|----------|------|
| `E0007` | JSON parse error (any `JsonParsingError`) | `esError` | Error message from parser |
| `E0007` | Any other exception during parse | `esError` | "JSON error: {message}" |
| `E0009` | Empty JSON source | `esError` | -- |

#### YAML (`.yaml`, `.yml`)

| Aspect | Details |
|--------|---------|
| Validator | `config_validators.nim` - `YAMLValidator` |
| Method | Line-by-line structural analysis |

| Error Code | Condition | Severity | Hint |
|------------|-----------|----------|------|
| `E0007` | Empty mapping key (no key before `:`) | `esError` | -- |
| `E0007` | General YAML structural error | `esError` | -- |
| `E0009` | No content after stripping comments/blanks | `esError` | -- |
| `W1001` | Tab characters used for indentation | `esWarning` | "Use spaces for YAML indentation" |

Note: Empty YAML (only whitespace/comments) is `valid: true`.

#### TOML (`.toml`)

| Aspect | Details |
|--------|---------|
| Validator | `config_validators.nim` - `TOMLValidator` |
| Method | Line-by-line structural analysis |

| Error Code | Condition | Severity | Hint |
|------------|-----------|----------|------|
| `E0007` | Missing `=` in key-value pair | `esError` | "TOML uses `key = value` format" |
| `E0007` | Missing key before `=` | `esError` | -- |
| `E0007` | General TOML structural error | `esError` | -- |
| `E0009` | No content after stripping comments/blanks | `esError` | -- |