Skip to main content
Powerful static analysis system based on EmmyLua annotations, helping you discover potential issues during coding and maintain code quality.

​
Overview

EmmyLua’s diagnostic system provides real-time feedback on code quality, detecting errors, warnings, and potential issues as you type. The system is built on advanced static analysis techniques and leverages EmmyLua annotations for precise type checking.

Real-time Detection

Instant feedback as you type with no compilation required

Type Safety

Comprehensive type checking using EmmyLua annotations

Flexible Control

Fine-grained control via comments and configuration

Smart Analysis

Context-aware diagnostics that understand Lua semantics

​
Diagnostic Control

​
Comment-based Control

Control diagnostics at file-level or line-level using special comments.
Disable specific diagnostics for an entire file:
---@diagnostic disable: undefined-global
---@diagnostic disable: unused-local

-- All 'undefined-global' and 'unused-local' warnings
-- are suppressed in this file
globalVar = "allowed"
local unusedVar = 42
Usage:
  • Place at the top of your file
  • Can disable multiple diagnostic types
  • Affects entire file scope

​
Configuration File Control

Fine-tune diagnostic behavior globally through .emmyrc.json: 
{
  "diagnostics": {
    "disable": [
      "undefined-global",
      "unused-local",
      "unused-parameter"
    ],
    "enable": [
      "deprecated"
    ],
    "severity": {
      "undefined-global": "error",
      "unused-local": "warning",
      "deprecated": "information",
      "type-check": "error"
    }
  }
}
Options:
  • disable - Array of diagnostic codes to disable globally
  • enable - Array of diagnostic codes to explicitly enable
  • severity - Override severity levels for specific diagnostics

​
Diagnostic Types

​
Type Checking Diagnostics

Detects usage of undefined global variables.
-- Error: undefined global 'unknownVar'
print(unknownVar)

-- Fix: Define or declare the variable
---@type string
local myVar = "defined"
print(myVar)

-- Or declare as global
---@diagnostic disable-next-line: undefined-global
---@type string
GLOBAL_VAR = "global"
Validates type compatibility in assignments and function calls.
---@param count number
local function setCount(count)
    -- Implementation
end

-- Error: expected number, got string
setCount("not a number")

-- Correct usage
setCount(42)
Detects access to undefined table fields.
---@class User
---@field name string
---@field age number
local User = {}

---@type User
local user = { name = "John", age = 30 }

-- Error: undefined field 'email'
print(user.email)
Warns about usage of deprecated functions or fields.
---@deprecated Use newFunction instead
local function oldFunction()
    -- Implementation
end

-- Warning: oldFunction is deprecated
oldFunction()

​
Code Quality Diagnostics

Detects unused local variables.
local function process()
    local unusedVar = 42 -- Warning: unused local variable
    local usedVar = 10
    return usedVar
end

-- Fix: Remove unused variable or prefix with underscore
local function process()
    local _unusedVar = 42 -- No warning (convention)
    local usedVar = 10
    return usedVar
end
Detects unused function parameters.
-- Warning: parameter 'b' is unused
local function add(a, b)
    return a
end

-- Fix: Use underscore prefix for intentionally unused parameters
local function add(a, _b)
    return a
end
Detects code that can never be executed.
local function example()
    return true
    print("unreachable") -- Warning: unreachable code
end
Detects duplicate field assignments in table constructors.
local config = {
    timeout = 30,
    retries = 3,
    timeout = 60 -- Warning: duplicate field 'timeout'
}

​
Syntax Diagnostics

Detects syntax errors in Lua code.
-- Error: unexpected symbol
local function test(
    print("missing closing parenthesis")
end
Detects functions that should return a value but don’t.
---@return number
local function getValue()
    -- Warning: missing return statement
end

​
Severity Levels

Diagnostics are categorized into four severity levels:

Error

Critical issues that will likely cause runtime errors

Warning

Potential problems that should be reviewed

Information

Informational messages and suggestions

Hint

Subtle hints for code improvements

​
Pull Diagnostics

EmmyLua supports LSP pull diagnostics, providing:
  • Document Diagnostics: Diagnostics for a specific file
  • Workspace Diagnostics: Diagnostics across the entire workspace
  • Inter-file Dependencies: Understanding cross-file issues
-- Changes in this file may affect diagnostics in other files
---@class Config
local Config = {}

function Config:getValue()
    return self.value
end

return Config

​
Best Practices

1

Use EmmyLua Annotations

Add type annotations to your code for better diagnostic accuracy:
---@param name string The user's name
---@param age number The user's age
---@return boolean success Whether the operation succeeded
local function registerUser(name, age)
    -- Implementation with full type checking
    return true
end
2

Configure Appropriately

Adjust diagnostic settings to match your project’s needs:
{
  "diagnostics": {
    "severity": {
      "undefined-global": "warning",
      "unused-local": "hint"
    }
  }
}
3

Suppress Wisely

Use diagnostic suppression sparingly and document why:
-- Using global from external library
---@diagnostic disable-next-line: undefined-global
local result = EXTERNAL_GLOBAL_FUNCTION()
4

Fix Issues Promptly

Address diagnostics as they appear rather than accumulating technical debt.
Overusing ---@diagnostic disable can hide real issues. Use it judiciously and only when necessary.
Configure severity levels to match your team’s coding standards and gradually increase strictness as your codebase matures.

Build docs developers (and LLMs) love

Get started for freeTalk to us