nimcheck/docs/API.md

# 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

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

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

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