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 --