Linter

Wippy includes a built-in linter that performs type checking and static analysis on Lua code. Run it with wippy lint.

Usage

wippy lint                        # Check all Lua entries
wippy lint --level hint           # Show all diagnostics including hints
wippy lint --json                 # Output in JSON format
wippy lint --ns app               # Check only the app namespace
wippy lint --summary              # Group results by error code

What Gets Checked

The linter validates all Lua entry kinds:

• function.lua.* - Functions
• library.lua.* - Libraries
• process.lua.* - Processes
• workflow.lua.* - Workflows

Each entry is parsed, type-checked, and analyzed for correctness issues.

Severity Levels

Diagnostics have three severity levels:

Control which levels appear with --level:

wippy lint --level error          # Errors only
wippy lint --level warning        # Warnings and errors (default)
wippy lint --level hint           # Everything

Error Codes

Parse Errors

Type Check Errors (E-series)

Type checker errors (E0001+) report issues found by the type system: type mismatches, undefined variables, invalid operations, and similar correctness problems. These are always reported as errors.

local x: number = "hello"         -- E: string not assignable to number

local function add(a: number, b: number): number
    return a + b
end

add("one", "two")                  -- E: string not assignable to number

Lint Rule Warnings (W-series)

Lint rules provide style and quality checks. Enable them with --rules:

wippy lint --rules

Without --rules, only type checking (P and E codes) is performed.

Filtering

By Namespace

Check specific namespaces using --ns:

wippy lint --ns app               # Exact namespace match
wippy lint --ns "app.*"           # All under app
wippy lint --ns app --ns lib      # Multiple namespaces

Dependencies of selected entries are loaded for type checking but their diagnostics are not reported.

By Error Code

Filter diagnostics by code:

wippy lint --code E0001
wippy lint --code E0001 --code E0004

By Count

Limit the number of diagnostics shown:

wippy lint --limit 10             # Show first 10 issues

Output Formats

Table Format (Default)

Each diagnostic is displayed with source context, file location, and the error message. Results are sorted by entry, severity, and line number.

A summary line shows totals:

Checked 42 entries: 5 errors, 12 warnings

Summary Format

Group diagnostics by namespace and error code:

wippy lint --summary

By namespace:

  app                              15 issues (5 errors, 10 warnings)
  lib                               2 issues (2 warnings)

By error code:

  E0001      [error  ]    5 occurrences
  E0004      [error  ]    3 occurrences

Checked 42 entries: 5 errors, 12 warnings

JSON Format

Machine-readable output for CI/CD integration:

wippy lint --json

{
  "diagnostics": [
    {
      "entry_id": "app:handler",
      "code": "E0001",
      "severity": "error",
      "message": "string not assignable to number",
      "line": 10,
      "column": 5
    }
  ],
  "total_entries": 42,
  "error_count": 5,
  "warning_count": 12,
  "hint_count": 0
}

Caching

The linter caches results to speed up repeated runs. Cache keys are based on source code hash, method name, dependencies, and type system configuration.

Clear the cache if results seem stale:

wippy lint --cache-reset

CI/CD Integration

Use JSON output and exit codes for automated checks:

wippy lint --json --level error > lint-results.json

The linter exits with code 0 when no errors are found, and non-zero when there are errors.

Example GitHub Actions step:

- name: Lint
  run: wippy lint --level warning

Flags Reference

See Also

• CLI - Full CLI reference
• Types - Type system documentation
• LSP - Editor integration with live diagnostics