API Reference

Function signatures, data types, and JSON output schemas for the Nimcheck library.

Core Functions

All functions are exported from nimcheck.nim. Import once with import nimcheck.

Validation

Function	Signature	Returns	Description
`validateSource`	`(source: string, flavor: LanguageFlavor = lfUnknown, options: ValidationOptions = newValidationOptions(), sourcePath: string = "")`	`ValidationResult`	Validate source code string. Auto-detects flavor if `lfUnknown`.
`validateFile`	`(filePath: string, flavor: LanguageFlavor = lfUnknown, options: ValidationOptions = newValidationOptions())`	`ValidationResult`	Validate a file from disk. Auto-detects flavor from file extension.
`validateSourceJson`	`(source: string, flavor: LanguageFlavor = lfUnknown)`	`string`	Validate and return pretty-printed JSON string.
`validateFileJson`	`(filePath: string, flavor: LanguageFlavor = lfUnknown)`	`string`	Validate file and return pretty-printed JSON string.

Inspection

Function	Signature	Returns	Description
`inspectSource`	`(source: string, flavor: LanguageFlavor = lfUnknown, options: ValidationOptions = newValidationOptions(), sourcePath: string = "")`	`JsonNode`	Validate and return structural diagnostics (functions, classes, imports).
`inspectFile`	`(filePath: string, flavor: LanguageFlavor = lfUnknown, options: ValidationOptions = newValidationOptions())`	`JsonNode`	Inspect a file and return structural diagnostics.

Reporting

Function	Signature	Returns	Description
`reportSource`	`(source: string, flavor: LanguageFlavor = lfUnknown)`	`string`	Human-readable validation report for source code.
`reportFile`	`(filePath: string, flavor: LanguageFlavor = lfUnknown)`	`string`	Human-readable validation report for a file.

Detection and Utility

Function	Signature	Returns	Description
`detectFlavor`	`(source: string, filePath: string = "")`	`LanguageFlavor`	Auto-detect language flavor (convenience wrapper).
`supportedFlavors`	`()`	`seq[string]`	List all registered language flavors sorted alphabetically.
`version`	`()`	`string`	Version string (`"0.1.0"`).
`enableDebug`	`()`	`void`	Enable debug mode globally.
`disableDebug`	`()`	`void`	Disable debug mode globally.

Core Detector (lower-level)

Function	Signature	Returns	Description
`detectFlavor` (core)	`(source: string, filePath: string = "", explicitFlavor: LanguageFlavor = lfUnknown)`	`(LanguageFlavor, FlavorDetectionMethod, float)`	Full detection with confidence score.

Factory

Function	Signature	Returns	Description
`createValidator`	`(flavor: LanguageFlavor, source: string, options: ValidationOptions, sourcePath: string)`	`ValidatorBase`	Factory: create the correct validator for a flavor.
`registerValidator`	`(flavor: string, constructor: ValidatorConstructor)`	`void`	Register a new validator constructor.

Data Types

LanguageFlavor (enum, pure)

All 28 flavors in src/nimcheck/core/types.nim have dedicated validators (v0.1.0). Registry aliases (e.g. py, js, md) map to the same validators — see supportedFlavors() or bin/nimcheck help.

Enum Value	String	Validator module	File Extensions (auto-detect)
`lfUnknown`	`"unknown"`	--	--
`lfNim`	`"nim"`	`nim_validator.nim`	`.nim`, `.nims`, `.nimble`
`lfPython`	`"python"`	`python_validator.nim`	`.py`, `.pyw`, `.pyx`, `.pxd`
`lfBash`	`"bash"`	`bash_validator.nim`	`.sh`, `.bash`
`lfShell`	`"shell"`	`bash_validator.nim` (shared)	`.zsh`, `.fish`
`lfJavaScript`	`"javascript"`	`javascript_validator.nim`	`.js`, `.mjs`, `.cjs`
`lfTypeScript`	`"typescript"`	`type_xml_validator.nim`	`.ts`, `.tsx`
`lfPHP`	`"php"`	`php_validator.nim`	`.php`, `.phtml`
`lfHTML`	`"html"`	`html_validator.nim`	`.html`, `.htm`, `.xhtml`
`lfXML`	`"xml"`	`type_xml_validator.nim`	`.xml`, `.xsd`, `.xslt`, `.svg`
`lfJinja`	`"jinja"`	`jinja_validator.nim`	`.jinja`, `.jinja2`, `.j2`
`lfJSON`	`"json"`	`config_validators.nim`	`.json`, `.jsonc`
`lfYAML`	`"yaml"`	`config_validators.nim`	`.yaml`, `.yml`
`lfTOML`	`"toml"`	`config_validators.nim`	`.toml`
`lfCSS`	`"css"`	`extended_validators.nim`	`.css`
`lfSQL`	`"sql"`	`extended_validators.nim`	`.sql`
`lfMarkdown`	`"markdown"`	`extended_validators.nim`	`.md`, `.markdown`
`lfDockerfile`	`"dockerfile"`	`extended_validators.nim`	`Dockerfile`
`lfMakefile`	`"makefile"`	`extended_validators.nim`	`Makefile`, `makefile`
`lfRuby`	`"ruby"`	`extended_validators.nim`	`.rb`
`lfRust`	`"rust"`	`extended_validators.nim`	`.rs`
`lfGo`	`"go"`	`extended_validators.nim`	`.go`
`lfLua`	`"lua"`	`lang_validators.nim`	`.lua`
`lfC`	`"c"`	`cfamily_validators.nim`	`.c`, `.h`
`lfCpp`	`"cpp"`	`cfamily_validators.nim`	`.cpp`, `.cxx`, `.hpp`
`lfCSharp`	`"csharp"`	`cfamily_validators.nim`	`.cs`
`lfJava`	`"java"`	`cfamily_validators.nim`	`.java`
`lfSwift`	`"swift"`	`lang_validators.nim`	`.swift`
`lfKotlin`	`"kotlin"`	`lang_validators.nim`	`.kt`, `.kts`

FlavorDetectionMethod (enum)

Value	Meaning
`fdmExplicit`	User explicitly provided the flavor
`fdmExtension`	Detected from file extension
`fdmShebang`	Detected from `#!` shebang line
`fdmContent`	Detected via content keyword analysis
`fdmUnknown`	Could not determine

TokenKind (enum)

Lexical token classifications used by all tokenizers.

Kind	Description
`tkWhitespace`	Spaces, tabs, carriage returns
`tkNewline`	`\n`
`tkComment`	Line (`#`, `//`) or block (`/* */`) comment
`tkDocComment`	Documentation comment (`##`, `///`, `"""`)
`tkString`	Single or double quoted string literal
`tkRawString`	Raw string (`r"..."`)
`tkMultilineString`	Triple-quoted string (`"""..."""`)
`tkNumber`	Integer, float, hex, octal, binary
`tkIdentifier`	Variable, function, type name
`tkKeyword`	Language-specific reserved word
`tkOperator`	`+`, `-`, `*`, `/`, `&&`, etc.
`tkAssignment`	`=`, `:=`, `+=`, etc.
`tkPunctuation`	`.`, `,`, `;`, `:`
`kOpenParen`	`(`
`kCloseParen`	`)`
`kOpenBracket`	`[`
`kCloseBracket`	`]`
`kOpenBrace`	`{`
`kCloseBrace`	`}`
`kAngleOpen`	`<`
`kAngleClose`	`>`
`tkInterpolation`	String interpolation (`${var}`, f-string `{expr}`)
`tkDirective`	Preprocessor / compiler directive (`#include`, shebang)
`tkTemplateTag`	Template language tag (`{{ }}`, `{% %}`)
`tkSpecial`	Language-specific special token
`tkError`	Malformed or unrecognizable character
`tkEndOfFile`	End of input marker

Token

Token = object
  kind: TokenKind
  value: string
  position: SourcePosition
  range: SourceRange

SourcePosition

SourcePosition = object
  line: int      # 1-indexed line number
  column: int    # 1-indexed column number
  offset: int    # 0-indexed byte offset from start

SourceRange

SourceRange = object
  startPos: SourcePosition
  endPos: SourcePosition

ErrorSeverity (enum)

Value	String	Description
`esInfo`	`"info"`	Informational note
`esWarning`	`"warning"`	Non-fatal issue
`esError`	`"error"`	Validation failure
`esCritical`	`"critical"`	Internal framework failure

ValidationError

ValidationError = object
  severity: ErrorSeverity
  message: string
  code: string           # Error code, e.g. "E0002"
  position: SourcePosition
  range: SourceRange
  context: string        # Surrounding source context (optional)
  hint: string           # Fix suggestion (optional)

ValidationResult

ValidationResult = object
  valid: bool
  flavor: LanguageFlavor
  detectionMethod: FlavorDetectionMethod
  errors: seq[ValidationError]
  warnings: int
  infos: int
  moduleInfo: ModuleInfo
  durationMs: float
  debugOutput: string     # Empty unless compiled with -d:nimcheckDebug

ValidationOptions

ValidationOptions = object
  flavor: LanguageFlavor        # lfUnknown = auto-detect (default)
  debugMode: bool               # Enable per-validation debug logging (default: false)
  strictMode: bool              # Warnings become errors (default: false)
  maxErrors: int                # Stop after N errors; 0 = unlimited (default: 0)
  includeContext: bool          # Include surrounding source lines in error output (default: true)
  includeHints: bool            # Include fix suggestions (default: true)

Structural Types (populated by `analyzeTokens()`)

VariableInfo = object
  name: string
  kind: string             # "var", "let", "const", "global", "local"
  typeAnnotation: string
  defaultValue: string
  position: SourcePosition
  mutable: bool
  exported: bool

FunctionInfo = object
  name: string
  kind: string             # "function", "method", "proc", "func", "lambda"
  parameters: seq[ParameterInfo]
  returnType: string
  isAsync: bool
  isExported: bool
  isGenerator: bool
  visibility: string       # "public", "private", "protected"
  position: SourcePosition
  docComment: string

ParameterInfo = object
  name: string
  typeAnnotation: string
  defaultValue: string
  isOptional: bool
  isVarargs: bool

ClassInfo = object
  name: string
  kind: string             # "class", "object", "struct", "interface"
  baseTypes: seq[string]
  fields: seq[VariableInfo]
  methods: seq[FunctionInfo]
  generics: seq[string]
  visibility: string
  position: SourcePosition
  docComment: string

ImportInfo = object
  module: string
  symbols: seq[string]     # Specific imported symbols
  isRelative: bool
  alias: string
  position: SourcePosition

ModuleInfo = object
  flavor: LanguageFlavor
  detectionMethod: FlavorDetectionMethod
  imports: seq[ImportInfo]
  variables: seq[VariableInfo]
  functions: seq[FunctionInfo]
  classes: seq[ClassInfo]
  linesOfCode: int
  totalTokens: int
  comments: int
  debugInfo: JsonNode      # Language-specific extra info

JSON Output Structures

Every type has a .toJson() method. The ValidationResult.toJson() aggregates all nested structures.

ValidationResult JSON

{
  "valid": true,
  "flavor": "python",
  "detectionMethod": "by_extension",
  "errors": [
    {
      "severity": "error",
      "message": "Unclosed string literal starting with '\"'",
      "code": "E0002",
      "position": {"line": 2, "column": 13, "offset": 42},
      "range": {
        "start": {"line": 2, "column": 13, "offset": 42},
        "end":   {"line": 2, "column": 13, "offset": 42}
      },
      "context": "",
      "hint": "Add a closing quote before end of file"
    }
  ],
  "warnings": 0,
  "infos": 0,
  "moduleInfo": {
    "flavor": "python",
    "detectionMethod": "by_extension",
    "imports": [],
    "variables": [],
    "functions": [
      {
        "name": "hello",
        "kind": "def",
        "parameters": [],
        "returnType": "",
        "isAsync": false,
        "isExported": false,
        "isGenerator": false,
        "visibility": "",
        "position": {"line": 1, "column": 5, "offset": 4},
        "docComment": ""
      }
    ],
    "classes": [],
    "linesOfCode": 3,
    "totalTokens": 12,
    "comments": 0,
    "debugInfo": null
  },
  "durationMs": 0.342,
  "debugOutput": ""
}

ValidationError JSON

{
  "severity": "error",
  "message": "Unclosed string literal starting with '\"'",
  "code": "E0002",
  "position": {"line": 2, "column": 13, "offset": 42},
  "range": {
    "start": {"line": 2, "column": 13, "offset": 42},
    "end":   {"line": 2, "column": 13, "offset": 42}
  },
  "context": "",
  "hint": "Add a closing quote before end of file"
}

ModuleInfo JSON

{
  "flavor": "nim",
  "detectionMethod": "by_extension",
  "imports": [
    {
      "module": "strutils",
      "symbols": [],
      "isRelative": false,
      "alias": "",
      "position": {"line": 1, "column": 8, "offset": 7}
    }
  ],
  "variables": [],
  "functions": [
    {
      "name": "add",
      "kind": "proc",
      "parameters": [],
      "returnType": "",
      "isAsync": false,
      "isExported": false,
      "isGenerator": false,
      "visibility": "",
      "position": {"line": 3, "column": 6, "offset": 28},
      "docComment": ""
    }
  ],
  "classes": [
    {
      "name": "MyType",
      "kind": "type",
      "baseTypes": [],
      "fields": [],
      "methods": [],
      "generics": [],
      "visibility": "",
      "position": {"line": 5, "column": 6, "offset": 52},
      "docComment": ""
    }
  ],
  "linesOfCode": 8,
  "totalTokens": 45,
  "comments": 2,
  "debugInfo": null
}

Human-Readable Report Format

=== Validation Report ===
  Flavor: python
  Detection: by_extension
  Valid: false
  Errors: 1
  Warnings: 0
  Duration: 0.34ms
  Lines of code: 3
  Tokens: 12

  --- Findings ---
  [E0002] (error) L2:13: Unclosed string literal starting with '"'
         |     x = "
         |            ^
         hint: Add a closing quote before end of file

  --- Summary ---
  INVALID - source has issues that need attention.

Error Formatter Output (single error)

  [E0002] (error) L2:13: Unclosed string literal starting with '"'
         |     x = "
         |            ^
         hint: Add a closing quote before end of file

CLI Usage

Nimcheck v0.1.0 - Universal Source Code Validation Framework

Usage:
  nimcheck validate [--file=<path> | --source=<code>] [--flavor=<lang>]
  nimcheck inspect  [--file=<path> | --source=<code>] [--flavor=<lang>]
  nimcheck detect   [--file=<path> | --source=<code>]
  nimcheck help

Options:
  --file=<path>     Source file to process
  --source=<code>   Source code string to process
  --flavor=<lang>   Language flavor (auto-detect if omitted)
  --debug           Enable debug mode
  --json            Output as JSON (default for inspect)

Run bin/nimcheck help for the current registered flavor list.

The validate command exits 0 at the process level; inspect valid in the output or JSON for pass/fail. Validation paths do not raise to the caller.