Diagnostics#

A diagnostic is a stable code, a severity, a source range, and a message, and every one the compiler reports carries all four whether a person or a program is reading. This is what one looks like on standard error:

src/main.nupp:8:13: error: NUPP2004: no field "horizonal" in Point
 8 | print(point.horizonal)
   |             ^~~~~~~~~
help: use the suggested field spelling

Text report#

The first line keeps the conventional compiler form, so a build tool that already reads file:line:column: severity: message needs no adapter for Nupp. Under it come the quoted source line and a caret run marking the primary range, then one note line per related location, then help.

Lines, columns, and offsets are 1-based byte positions. They are 0 when the file could not be read at all.

Lint names#

A lint carries its name after the code, so the thing a project would configure is visible in the line it printed:

src/main.nupp:4:5: warning: NUPP2107 exhaustiveness: every branch returns, so this handles "blue" | "green" | "red" and leaves "red" unhandled
help: add branches for "red" or add an else clause

That name is what an @allow suppression or a nupp.lua entry writes. See Lints for the built-in lints, their categories, and their default levels.

Color#

Written to a terminal the same report is colored: the severity and the caret run share a color, the code and lint name are dimmed, the file position and the message have their own, and so does the rail beside the quoted source. Written anywhere else it is exactly the text above, byte for byte.

--color=always and --color=never answer without looking at the stream. Failing an explicit flag, NO_COLOR refuses escapes, CLICOLOR_FORCE demands them, and failing both the stream is asked whether it is a terminal that understands them, which TERM=dumb answers no for.

Diagnostic fields#

Every diagnostic carries severity and message, plus fixes, notes, and related, which are always present and may be empty. The rest appear when there is something to say:

• range, on anything with a place in source. A diagnostic about something with none -- a file that could not be read, a manifest that could not be used -- leaves it out rather than pointing at a line 0 no file has.
• file and code, on anything with a file and a code of its own.
• help: a concrete repair direction, in one sentence.
• related: labeled secondary ranges, including ranges in other files.
• fixes: titled edit sets a tool can apply without reading the prose.
• notes: context that points at no source, such as the trace classification a JIT trace check attaches to its finding.
• lint: the lint name, when the code names one.
• docs: the reference section covering the code, always as a documentation path and an anchor: the prose section that owns the rule, or the code's own entry in the diagnostic index where no prose section does.

The language server converts the same data to UTF-16 LSP ranges, relatedInformation, diagnostic data, and code actions, so an editor and a terminal disagree about presentation and about nothing else.

Explaining a code#

nupp explain prints the rule behind a code, a program that reports it, the same program corrected, related codes, and a reference into these documents:

nupp explain NUPP2119

Every code with an entry can be looked up this way, which is faster than searching for the number. The diagnostic index below is the same content rendered as a page.

Code families#

The leading digit is the family, and every code falls in one, so a code with no entry of its own can still be resolved this far.

OPT-n is the one family that does not describe a problem. A pass reports one to say that it rewrote something, or that it looked at something and could not. The severity is always note, so a remark is reported and stepped over and never fails a build.

Remarks are off unless --remarks is passed, and they come from nupp build and nupp run rather than nupp check, which does not optimize. The code is stable across a pass being renamed, split, or merged, so it can be cited in a bug report or passed to -Zno-opt. See the performance guide for what each pass reports.

Codes by area#

A code is explained in full by the diagnostic index below, and in context by the page that owns the rule. This is the map from an area to that page:

A code appears in several rows when several rules can report it. NUPP2004 is one code for "that field is not there", and which page explains it depends on what was being reached for.

Repairs#

A fix is a title and a set of byte-ranged edits into one file, and applying it is all-or-nothing. Only unambiguous rewrites qualify: where a message lists alternatives, each alternative is its own fix rather than a guess between them.

The checker offers fixes for misspelled variables, type names, fields, methods, and metamethods; missing module qualifications and require statements; declaration visibility; a customary operator replaced with Lua's word; explicit casts for intended lossy narrowing; and the conversion that establishes a fixed-width value.

A diagnostic gives help rather than an edit when the compiler cannot choose a program on the author's behalf. Enum exhaustiveness cannot invent branch bodies, an ambiguous global cannot decide which public declaration should change visibility, and a resource without cleanup metadata cannot guess which function owns that responsibility.

Machine-readable output#

Every command whose result is data rather than a side effect takes --format json, with --json as its shorthand, and every command that takes it also takes --schema, which prints the JSON Schema of what --json writes and exits. The schema is declared beside the code that writes it and a test validates real output against it, so the two cannot drift.

nupp run is the exception. Its --json writes the --jit-aborts record as JSON instead of CSV, because the program's own output is the run's output.

Every command holds its --json to one contract, whichever way it ends:

• Exit status 2 is a usage error: an argument the command cannot use, decided from the arguments and the names compiled into the compiler. Nothing is written to stdout, even under --json; stderr has the usage message.
• Exit status 0 or 1 writes exactly one document to stdout, valid against the command's --schema, with ok set and equal to the status being 0.
• ok false always comes with at least one error in diagnostics that carries a code. A failure outside source is coded too; see Failures outside source.
• Nothing on stderr is needed to understand the result. It carries progress, when progress was asked for.

nupp test answers a failure before its tests started -- a manifest it could not use, a build under test that failed -- with the runner's own document: one failed record under a synthetic ID such as nupp/<build>.

The documents are not versioned. Their version is the compiler's, which nupp version --json reports, and --schema is the contract: it describes what this compiler writes, and a field may change between releases before 1.0. Artifacts another process reads back -- a coverage report, an AOT units manifest, a bench baseline -- are a different matter and carry a schemaVersion checked on read; see Versions.

The output is always valid UTF-8. A byte that is not UTF-8, such as one a diagnostic quotes from the source, is written as U+FFFD.

Failures outside source#

A command can stop before it has a file and a position to point at. Each such failure still has a code, so a caller reading --json can tell them apart without reading the message, and none has a range:

A directory with no nupp.lua is a supported configuration for the commands that can work without one, and reports nothing. One that has a manifest which does not load is NUPP0002, since answering without it would answer for a different project.

Agent workflow#

1. Run nupp check --json, and read ok first.
2. Apply a complete fix from diagnostics[].fixes when its title matches the intended repair. Never take individual edits out of one.
3. Read docs on a diagnostic, or run nupp explain <code> --json, when the message alone does not say what the rule is. For the surrounding prose rather than the rule, nupp reference --for <code> prints the sections that cover it, and nupp reference --section <anchor> takes the docs pointer itself. Either is a few hundred words where the chapter is thousands.
4. Inspect related locations before changing cross-file declarations or ownership transfers.
5. Use nupp lsp inspect, nupp lsp definition, and nupp lsp references when more semantic context is needed.
6. Re-run the check after each edit group, then nupp test --json before committing, which reports each failing test's name, message, file, and line rather than a wall of progress text.
7. Read timing.compiledModules and timing.slowest when a check of an unchanged project is slower than expected. compiledModules = 0 is the authoritative answer that nothing was redone, and slowest ranks modules by time actually spent either way, since confirming that a cache entry is still valid costs time too.

FAQ#

How do I stop the checker reporting a lint I do not want?#

Set the lint to off by name or by category in the lints table in nupp.lua, or decorate the one statement with @allow("lint-name"). See Lints for the resolution order, which runs registry default, then category, then name, then the @allow.

Why did a diagnostic give me help and no fix?#

Because more than one program would satisfy the rule and the compiler will not pick one. An unhandled enum member needs a branch body only the author knows, so the message says what is missing and stops. See Repairs for the repairs that are unambiguous enough to be offered as edits.

Why does a failed run have a diagnostic with no range?#

The run never reached a file. A manifest that could not be used ends a check before anything is parsed, so the reason is a coded diagnostic about the run -- NUPP0002 -- rather than about a place in source. See Failures outside source.

Why did @allow not silence an error?#

@allow reaches lints and nothing else, so naming a type error in one leaves the error standing and reports NUPP2108 for the name. See Lints for what counts as a lint.

Diagnostic index#

Every code the compiler reports specifically, with the rule it enforces and, where one is known, the program that reports it beside the same program corrected. nupp explain <code> prints the same thing in a terminal.

A code that resolves only through its family is not here. The families are the leading digit, and each one answers for every code under it.

Input#

NUPP0001#

A file could not be read or written.

The path named on the command line, reached from a require, or written as output could not be opened. Check the spelling and that the file is readable, or its directory writable, from the directory the compiler was run in. The diagnostic has no position: the run never got inside the file.

Related: NUPP0002. Reference: docs/reference/diagnostics.md#failures-outside-source.

NUPP0002#

The project manifest could not be used.

A nupp.lua that exists has to load and describe a project this compiler can build. One that raises, returns something other than a table, misspells a key, or asks for a combination the build cannot honour stops the command before any source is read, since answering without it would answer for a different project. A directory with no nupp.lua at all is a supported configuration and reports nothing.

Related: NUPP0001, NUPP0003. Reference: docs/reference/diagnostics.md#failures-outside-source.

NUPP0003#

A name the command was given names nothing here.

A build target, task, platform or triple is looked up in the manifest or among the targets this compiler models, and a function, position or kind of input in the file the command was pointed at. The name was well formed and names nothing there. nupp task --list lists the targets and tasks a project defines.

Related: NUPP0002. Reference: docs/reference/diagnostics.md#failures-outside-source.

NUPP0004#

A tool the command depends on failed.

Some commands hand part of their work to another program or component: LuaRocks installs a dependency, the LLVM kit compiles native code, Cargo builds a native provider, a C preprocessor reads a header, a stage compiler rebuilds the compiler. When that step fails, the message carries what it said. The source may be fine; what failed is the step.

Related: NUPP0002. Reference: docs/reference/diagnostics.md#failures-outside-source.

NUPP0005#

A type dependency's declaration file was not imported.

A kind = "types" dependency is somebody else's source, pinned at a revision this project chose but did not write. A file in that tree the importer cannot read, parse, or check is skipped and named here; the declarations beside it are still imported, so one unreadable corner of an API does not cost the project the rest of it. Pin a revision this compiler can read, or report the construct that stopped it.

Related: NUPP1008, NUPP1006. Reference: docs/learn/projects/integrations/luacats.md#recovery.

Syntax#

NUPP1001#

The lexer could not read a token to completion.

local s = 'oops
return 1

A string, long string, long comment, interpolation, or number must close or resolve within the input it is given: a quote must find its matching quote before the line ends, a long bracket must find its matching close, and a numeral must match the shape of a number. A byte that starts none of the lexer's tokens is reported the same way. Recovery marks the malformed span as an error token and resumes lexing from the next line.

local s = 'oops'
return s

Related: NUPP1002, NUPP1005. Open the reported program in the playground.

NUPP1002#

A required token is missing.

local function f(): integer
    if true then
        return 1
end

A construct was opened and not closed. The position reported is where the closing token was expected, which is the end of the file when nothing closed it at all.

local function f(): integer
    if true then
        return 1
    end
    return 0
end

Related: NUPP1004. Open the reported program in the playground.

NUPP1003#

A required name is missing.

local record Point
    x: number
end

local function show(p: Point): number
    return p.
end

return show

Certain tokens are always followed by a name: '.', 'function', 'for', 'as', '@', 'metamethod', and other positions where a declaration or reference names something. When the next token is not a name, the parser reports it there and inserts a zero-width name placeholder so parsing, and the source round trip, can continue.

local record Point
    x: number
end

local function show(p: Point): number
    return p.x
end

return show

Related: NUPP1002, NUPP1004. Open the reported program in the playground.

NUPP1004#

A required expression is missing.

local record Point
    x: integer
end

local bare = new Point

return bare

An expression position, whether a parenthesized operand, a call argument, or the whole of a value, must actually contain one; a token that cannot begin an expression is reported there and replaced with a zero-width placeholder. new is held to the same requirement in its own way: it takes a suffixed expression that must end in a call, since a bare new T would be a second spelling of new T().

local record Point
    x: integer
end

local made = new Point(x = 1)

return made

Related: NUPP1002, NUPP1003. Open the reported program in the playground.

NUPP1005#

Another syntax or recovery constraint failed.

return 1
local x = 2

The catch-all syntax code, used for a structural violation that is not a missing token, name, or expression: a return that is not the last statement in its block, a const path that is not static, expressions, blocks or types nested more than a thousand levels deep, and similar constraints the parser enforces directly. Each diagnostic's message names the specific rule that failed.

local x = 2
return x

Related: NUPP1002, NUPP1004. Open the reported program in the playground.

NUPP1006#

The typed layer appears in a plain Lua file.

A .lua file is Lua. The toolchain will require, build and run one unchanged, so typed Nupp syntax cannot be written into it. Rename the file .nupp to mean it. Type comments are separate: recognized LuaCATS, EmmyLua, and typed LuaDoc comments are always imported.

Related: NUPP2105, NUPP2106.

NUPP1007#

A docblock parameter does not exist.

--- @param valeu the value
local function keep(value: integer): integer
    return value
end
return keep(1)

An @param line documents one parameter of the declaration below it. Spell that parameter's source name exactly, or remove the line; otherwise generated documentation promises an argument the function does not accept.

--- @param value the value
local function keep(value: integer): integer
    return value
end
return keep(1)

Related: NUPP1010, NUPP2506. Reference: docs/learn/tooling/documentation.md#doc-comments. Open the reported program in the playground.

NUPP1008#

An annotated Lua type lost precision during import.

Type comments in a .lua file are always read. A malformed, ambiguous, unsupported, or ownership-incomplete foreign type recovers at the smallest affected position, usually as any, and checking continues.

Related: NUPP1006, NUPP2101. Reference: docs/learn/projects/integrations/luacats.md#recovery.

NUPP1010#

A docblock raise does not name a type.

--- Reads a name.
--- @raises when name is empty
local function read(name: string): string
    if name == "" then error("empty name") end
    return name
end
return read

An @raises line is written @raises Type the condition. The type is the value error is called with, so a caller reading the page knows what a pcall around the call hands back. Name a type this file can resolve, or string where the raise is an ordinary Lua message.

--- Reads a name.
--- @raises string when name is empty
local function read(name: string): string
    if name == "" then error("empty name") end
    return name
end
return read

Related: NUPP1007, NUPP2506. Reference: docs/learn/tooling/documentation.md#doc-comments. Open the reported program in the playground.

Types, declarations, and rules#

NUPP2001#

A value does not fit the type it is bound to.

local count: integer = "twelve"
return count

An annotated binding accepts only values of that type. The annotation is the claim; the initializer has to keep it.

local count: integer = 12
return count

Related: NUPP2002, NUPP2006. Open the reported program in the playground.

NUPP2002#

A returned value does not fit the declared result.

local function length(): integer
    return "long"
end

return length

A function's result annotation is a promise to every caller. Each returned value must fit its corresponding result type, and a function that declares several results must return the complete sequence.

local function length(): integer
    return 4
end

return length

Related: NUPP2001, NUPP2010. Reference: docs/learn/language/types/primitives.md#function-declarations. Open the reported program in the playground.

NUPP2003#

An operator's operand types cannot support what it does.

local lpeg = require("lpeg")
local pattern = lpeg.P("a") ^ "two"
return pattern

Arithmetic, comparison, concatenation, length, and LPeg's pattern algebra each accept a fixed set of operand shapes or a metamethod contract that stands in for one. LPeg's Pattern operators are compiler-provided rather than ordinary metamethods: *, +, and - need operands whose capture shapes can be combined, ^ needs an integer exponent, / needs a string, integer, function, or table transform, and % needs a function accumulator. An operand outside what the operator accepts is reported rather than run to see what happens.

local lpeg = require("lpeg")
local pattern = lpeg.P("a") ^ 2
return pattern

Related: NUPP2005, NUPP2006. Open the reported program in the playground.

NUPP2004#

The field does not exist on that type.

local record Point
    x: number
    y: number
end

local function show(p: Point): number
    return p.z
end

return show

A field read has to name a field the receiver's type actually has. When the name is close to a real one the diagnostic carries a fix that spells it correctly.

local record Point
    x: number
    y: number
end

local function show(p: Point): number
    return p.x
end

return show

Related: NUPP2005, NUPP2119. Open the reported program in the playground.

NUPP2005#

A call's callee has no callable type or __call contract.

local count: integer = 5
return count()

A call needs a function type, an intersection with at least one function member, or a receiver whose type contracts for __call. any is exempt, since it opts the value out of checking; anything else that is called is reported once, and its argument expressions are still checked so one mistake does not hide another.

local function callable(): integer
    return 5
end
return callable()

Related: NUPP2003, NUPP2006. Open the reported program in the playground.

NUPP2006#

A call's arguments are not arranged in a way it can be given.

local record Vec3
    x: number
    y: number
    z: number
end

local function draw(x: number, y: number): nil
    print(x, y)
end

local function make(): Vec3
    return new Vec3(x = 1, y = 2, z = 3)
end

draw({x, y} = make())

return draw

Named and plucked arguments follow every positional argument, so nothing positional may come after one. A plucked operand must be a name or dotted field path: each name it fills reads one field of that path, and confining it to a path is what lets those reads be unordered and the path be evaluated once. Bind a call or a computed index to a local and pluck from the local.

local record Vec3
    x: number
    y: number
    z: number
end

local function draw(x: number, y: number): nil
    print(x, y)
end

local function make(): Vec3
    return new Vec3(x = 1, y = 2, z = 3)
end

local position = make()
draw({x, y} = position)

return draw

Related: NUPP2004, NUPP2125. Reference: docs/learn/language/named-arguments.md#rejected-arrangements. Open the reported program in the playground.

NUPP2007#

A call passes more arguments than its callee accepts.

local function keep(value: integer): integer
    return value
end
return keep(1, 2)

A function that takes fewer parameters is usable where more are supplied, because ignoring trailing arguments is ordinary Lua; the reverse is an error unless the callee's parameter pack has a variadic tail to absorb the extras.

local function keep(value: integer): integer
    return value
end
return keep(1)

Related: NUPP2006, NUPP2010. Reference: docs/learn/language/types/primitives.md#function-declarations. Open the reported program in the playground.

NUPP2008#

A const binding or const module field is assigned to.

const count = 1
count = 2
return count

The const modifier on a local or a module field is a promise that nothing after its initializer changes it. An ordinary assignment or compound assignment to that name is refused, whether the binding is a local declared const, a builtin the prelude declares constant, or a field a module recorded as const on first assignment.

local count = 1
count = 2
return count

Related: NUPP2001, NUPP2602. Reference: docs/learn/language/types/primitives.md#const. Open the reported program in the playground.

NUPP2009#

A property view does not grant the requested access.

local out: {@writeonly value: string} = {}
local value = out.value
return value

A read-only property may be read but not assigned, and a write-only property may be assigned but not read. Use a view that declares the needed capability.

local out: {@writeonly value: string} = {}
out.value = "ready"
return out

Related: NUPP2004, NUPP2008. Reference: docs/learn/language/types/properties.md#access-diagnostics. Open the reported program in the playground.

NUPP2010#

A complete value pack does not fit the required sequence.

local value = select(0, 1, 2)
return value

Calls, returns, assignments, selection, and coroutine transfers compare complete Lua value sequences. Their fixed slots, optional tails, and correlated alternatives must agree; use parentheses only when intentionally projecting one ordinary value.

local first, second = select(1, 1, 2)
return first, second

Related: NUPP2002, NUPP2007, NUPP2121. Reference: docs/learn/language/types/packs.md#pack-compatibility. Open the reported program in the playground.

NUPP2011#

A fixed-width value was claimed without being established.

local input: number = 0.1
local value: float = input as float
return value

float, int32, and uint32 are checked refinements of Lua numbers. A fitting literal, a checked refined source, a reified load, or the explicit conversion establishes the claim; an erased as does not.

local input: number = 0.1
local value: float = nupp.math.f32.narrow(input)
return value

Related: NUPP2001, NUPP2002, NUPP2006, NUPP2012. Reference: docs/learn/language/types/primitives.md#value-refinements. Open the reported program in the playground.

NUPP2012#

A physical storage width was used as an ordinary value type.

local byte: uint8 = 1
return byte

int8, int16, uint8, and uint16 describe physical layout. Use them for struct fields, C arrays and pointers, cdefs, or span elements; use int32 or uint32 for locals, parameters, results, and record fields.

local byte: uint32 = 1
return byte

Related: NUPP2011, NUPP2201, NUPP2203. Reference: docs/learn/language/types/primitives.md#numbers. Open the reported program in the playground.

NUPP2013#

nupp.admit was written without a constrained destination or with the wrong value.

local type Small = nupp.types.range(integer, 0, 10)
local function of(v: integer): integer
    return nupp.admit(v)
end
return of

nupp.admit(value) takes the constrained type it admits into from where its result goes: an annotated binding, a declared result, or a parameter. A destination that is not constrained gives it nothing to establish, and a value that is not already the constraint's base is a conversion rather than an admission, which this does not do.

local type Small = nupp.types.range(integer, 0, 10)
local function of(v: integer): Small
    return nupp.admit(v)
end
return of

Related: NUPP2011, NUPP2422. Open the reported program in the playground.

NUPP2101#

A type name cannot be resolved.

local count: Count = 1
return count

A type name must be a built-in, a declaration visible in this file, or a member reached through its module. Declare the type, require the module that exports it, or correct its spelling.

local type Count = integer
local count: Count = 1
return count

Related: NUPP2105, NUPP2120. Open the reported program in the playground.

NUPP2102#

Two project globals declare the same type name.

A global declaration is reachable project-wide with no require, so globals share one flat namespace across every file. When two files each declare a global type of the same name, an unqualified use of that name cannot know which declaration it means, and both declaring locations are reported. This is inherently a whole-project condition: within the file that declares a name, its own declaration is already in scope directly and this check is not reached, so a single isolated file cannot exhibit it on its own.

Related: NUPP2104, NUPP2101.

NUPP2104#

Two project globals declare the same value name.

A global record or global struct declaration puts a value in _G as well as a type in the project's global type namespace. When two files each declare a global of the same name whose value side collides, an unqualified use of that name as a value cannot know which declaration it means, and both declaring locations are reported. Like NUPP2102, this is a whole-project condition: a file that declares the name resolves its own declaration directly and never reaches this check, so a single isolated file cannot exhibit it on its own.

Related: NUPP2102, NUPP2120.

NUPP2105#

A name is not any value the checker or project can account for.

local function shout(text: string): string
    return txet .. "!"
end
return shout

A name the checker cannot account for is reported unless it is a project module's basename, with a spelling fix offered when a visible name is close enough to be the one meant. A .lua file reports none, since an unknown name there may be a Lua global set at run time.

local function shout(text: string): string
    return text .. "!"
end
return shout

Related: NUPP2120, NUPP2101. Open the reported program in the playground.

NUPP2106#

An exported declaration needs a type annotation.

local m = {}

function m.double(n)
    return n * 2
end

return m

What a module returns is its interface, and an interface is written down rather than inferred. A function attached to the module table needs its parameter and result types, and a signature mentioning any counts as unwritten. A .d.nupp file may write any, since it describes code somebody else implements.

local m = {}

function m.double(n: integer): integer
    return n * 2
end

return m

Related: NUPP2119. Open the reported program in the playground.

NUPP2107#

A dispatch leaves members of a closed set unhandled.

local type Color = 'red' | 'green' | 'blue'

local function name(c: Color): string
    if c == 'red' then return "red" end
    return "other"
end

return name

When every branch returns, the dispatch is exhaustive or it is not, and the checker can tell which. Add the missing branches, or an else that says the rest are deliberately alike.

local type Color = 'red' | 'green' | 'blue'

local function name(c: Color): string
    if c == 'red' then
        return "red"
    elseif c == 'green' then
        return "green"
    else
        return "blue"
    end
end

return name

Reported by the exhaustiveness lint, category correctness, at warning by default. Configure it by name or by category.

Related: NUPP2004. Reference: docs/reference/lints.md#exhaustiveness. Open the reported program in the playground.

NUPP2108#

A type error is named as though it were a lint.

@allow(NUPP2001)
local count: integer = "one"
return count

@allow suppresses lint judgements, by lint name or code. A type error says the program cannot keep its own type claims, so it cannot be configured or silenced; correct that error instead.

local count: integer = 1
return count

Related: NUPP2001, NUPP2112. Reference: docs/reference/lints.md#local-suppressions. Open the reported program in the playground.

NUPP2109#

A name written to select a parameter or captured value resolves to nothing.

local record R
    x: integer
end

local function f(a: R): b is R
    return true
end

return f

Several forms name a parameter or a value already in scope rather than introduce one: a predicate's x is T result names the tested parameter, and a closure's takes (...) or borrows (...) clause names values it captures. Each such name must resolve to an actual parameter of the enclosing function, or an actual value visible where the closure is written; a name that answers to nothing there is reported rather than silently ignored.

local record R
    x: integer
end

local function f(a: R): a is R
    return true
end

return f

Related: NUPP2110. Reference: docs/learn/language/types/narrowing.md#predicate-functions. Open the reported program in the playground.

NUPP2110#

A predicate's tested parameter could never hold the narrowed type.

local record R
    x: integer
end

local function f(a: string): a is R
    return true
end

return f

A predicate's return type param is T is trusted rather than verified for what the body proves, but the checker still confirms the shape is coherent: the named parameter's declared type must be able to hold T. When the two types are disjoint the predicate can never truthfully hold, so it is refused rather than compiled as narrowing that could never fire.

local record R
    x: integer
end

local function f(a: R): a is R
    return true
end

return f

Related: NUPP2109. Reference: docs/learn/language/types/narrowing.md#predicate-functions. Open the reported program in the playground.

NUPP2111#

An annotation name does not resolve to a definition.

@inline
local function f(): nil
end

return f

An @name application resolves name against a definition: a compiler built-in, or a project declaration reached with @annotation. Applying a name nothing defines, or one a project's own resolution reports an error for, is refused rather than treated as an inert comment.

local function f(): nil
end

return f

Related: NUPP2112, NUPP2114. Reference: docs/reference/annotations.md#defining-an-annotation. Open the reported program in the playground.

NUPP2112#

An annotation is applied where its definition forbids it, or with arguments outside its declared shape.

@jit
local x = 1

return x

A definition's targets set is the complete list of constructs an application may decorate, and its argument policy (none, names, effects, warnings, typed) is the complete shape its arguments may take. An application outside either is refused rather than silently accepted.

@jit
local function f(): nil
end

return f

Related: NUPP2111, NUPP2115. Reference: docs/reference/annotations.md#attachment-targets. Open the reported program in the playground.

NUPP2113#

A reserved built-in annotation is applied before its behavior is implemented.

A built-in definition may carry a reservation naming the feature it is waiting on, ahead of the feature existing. Applying that name still parses and resolves, since the definition is real, but is refused with what it is reserved for rather than silently accepted and doing nothing. No shipped built-in currently carries a reservation -- the mechanism exists for a name registered ahead of its implementation, as @jit itself once was.

Related: NUPP2111, NUPP2112.

NUPP2114#

@annotationValue or @ref is used outside an annotation-definition field, or a definition's own shape is invalid.

local record Plain
    @annotationValue
    x: string
end

@annotationValue and @ref are meaningful only on a field inside a record or struct itself marked @annotation, and @annotation takes exactly one named targets argument: a non-empty array of target-name string literals. Any of these written where that context is missing describes a definition that cannot exist.

@annotation(targets = {"record"})
local record Plain
    @annotationValue
    x: string
end

Related: NUPP2115, NUPP2112. Reference: docs/reference/annotations.md#single-value-applications. Open the reported program in the playground.

NUPP2115#

A typed annotation's argument does not fit its member, or is not a compile-time constant.

@syntax(42)
local value = 1

return value

A typed-argument annotation checks each supplied argument against the member it names: the value must fit the member's declared type, a @ref member must resolve to a compatible type reference, no member may be supplied twice, and every required member must be supplied. Only the member marked @annotationValue may be supplied positionally.

@syntax("json")
local value = 1

return value

Related: NUPP2114, NUPP2112. Reference: docs/reference/annotations.md#built-in-annotations. Open the reported program in the playground.

NUPP2116#

A type argument, or an associated-type answer, does not fit its declared bound.

local interface Named
    name: string
end

local interface Tagged
    associated type Tag is Named = integer
end

return Tagged

A T is Bound constraint, wherever it is written -- a generic type parameter or an associated type's own bound -- is checked where the argument is supplied: at a generic's instantiation, or at the default or answer that fills the associated type. An any argument skips the check; any other concrete type must actually satisfy the bound.

local interface Named
    name: string
end

local interface Tagged
    associated type Tag is Named = Named
end

return Tagged

Related: NUPP2117, NUPP2003. Reference: docs/learn/language/types/generics.md#constraints-use-is. Open the reported program in the playground.

NUPP2117#

A declaration names an invalid interface after is.

local record Other
end

local record Bad is Other
end

return Bad

Only an interface may appear after is on a record, struct, or interface declaration, because that is the only declaration kind able to state a contract for another to inherit. An interface cannot implement itself, directly or through other interfaces: the declared hierarchy must be acyclic. A record, struct, alias, or any other named value is refused there even when its shape happens to match.

local interface Other
end

local record Bad is Other
end

return Bad

Related: NUPP2116, NUPP2136. Reference: docs/learn/language/types/interfaces.md#is-is-a-claim-not-a-proof. Open the reported program in the playground.

NUPP2118#

A declaration contains an invalid or conflicting member.

local record Pair
    first: string
    first: integer
end

return Pair

A declaration has one member of a given name and capability. Duplicate fields, methods with the same parameter pack, conflicting static and instance members, unknown metamethods, and incompatible interface overrides cannot describe one coherent contract. A method overriding a child interface's inherited slot must say @override; a concrete implementor needs it when replacing inherited default behavior.

local record Pair
    first: string
    second: integer
end

return Pair

Related: NUPP2004, NUPP2123. Open the reported program in the playground.

NUPP2119#

A declaration does not say where it lives.

record Loose
    id: integer
end

return Loose

A declaration is file-local (local), a member of a table (record m.R), or a project global (global). Plain Lua would have made it a global silently; Nupp asks instead, because a name that means one thing here and another elsewhere is worth one word to prevent.

local record Loose
    id: integer
end

return Loose

Related: NUPP2106, NUPP2120. Open the reported program in the playground.

NUPP2120#

A project module is used without being required.

local answer: number = mathutil.double(21)
return answer

A project file does not put its basename into every other file's scope. Bind the module with require before reading its members; the diagnostic names the require call that makes the program valid.

local mathutil = require("mathutil")
local answer: number = mathutil.double(21)
return answer

Reported by the missing-require lint, category correctness, at error by default. Configure it by name or by category.

Related: NUPP2101, NUPP2105. Reference: docs/learn/language/modules.md#naming-a-member-from-another-file. Open the reported program in the playground.

NUPP2121#

A type pack is used where only one value type can appear.

local value: (number, string)
return value

A pack binder must follow every ordinary type binder, and a pack may appear only in a sequence position: function parameters or results, a coroutine protocol, a pack-union arm, or an explicit pack argument.

local function pair(): (number, string)
    return 1, "one"
end
return pair

Related: NUPP2010. Reference: docs/learn/language/types/packs.md#syntax. Open the reported program in the playground.

NUPP2122#

A refinement cannot be enforced.

local interface Circle
    kind: string

    satisfies |self| -> tostring(self.kind) == "circle"
end

return Circle

A satisfies declaration names the runtime test that decides whether a value is one of these, and x is T compiles to it. That test has to run wherever is is written, so it reads the declaration's own fields through self and nothing else: comparisons against literals, type() tests, and, or, not. A call, arithmetic, or a name from outside the subject cannot be evaluated there. A refinement that always answers the same way is also refused, since always true identifies every value and always false leaves the type uninhabited, and so is one on a struct, which ffi.istype already answers exactly.

A declaration is also held to the refinements of the interfaces it declares. record C is Shape is a claim the checker proves, and Shape's refinement is what is Shape runs, so fields that make that test fail would leave the two disagreeing about the same value. Only a provable failure is reported: a refinement whose answer no declaration settles is not evidence of a mistake.

local interface Circle
    kind: string

    satisfies |self| -> self.kind == "circle"
end

return Circle

Related: NUPP2116. Reference: docs/learn/language/types/refinements.md#tests-read-self-and-nothing-else. Open the reported program in the playground.

NUPP2123#

A metatable value does not fit the key it is written under.

local record I64
    v: integer
    metamethod __add: function(self: I64, other: I64): I64
end

local x = new I64(v = 1)
setmetatable(x, {__add = "not a function"})

return x

A metamethod declaration is a contract, and a metatable literal is where the value fulfilling it is written, so the value is held to it, with self specialized to the receiver, through a bounded type parameter as readily as through a concrete type. Where the declaration contracts for nothing, LuaJIT still says what it will do with the key: __mode is read as a string, __index and __newindex are a table to defer to or a function to run, and everything else it knows is called.

Only a literal is checked. What a function returns cannot be seen from here, so a computed metatable stays unchecked.

local record I64
    v: integer
    metamethod __add: function(self: I64, other: I64): I64
end

local x = new I64(v = 1)
setmetatable(x, {__add = function(a: I64, b: I64): I64
    return new I64(v = a.v + b.v)
end})

return x

Related: NUPP2118, NUPP2006. Reference: docs/learn/language/metamethods.md#checking-a-metatable-literal. Open the reported program in the playground.

NUPP2124#

An intersection is provably uninhabited.

local type Impossible = string & number
return Impossible

A value of A & B must satisfy both contracts. Nupp reports only finite proofs of impossibility, such as distinct runtime categories, literal tags, concrete nominal identities, or incompatible required fields; an intersection it cannot disprove remains legal.

local type NamedValue = {name: string} & {value: number}
return NamedValue

Related: NUPP2125, NUPP2126. Reference: docs/learn/language/types/intersections.md#provable-emptiness. Open the reported program in the playground.

NUPP2125#

No overload accepts a call.

local type F = function(integer): string & function(string): boolean
local f: F = nil as any
return f(true)

A callable intersection probes every function member against the same adjusted argument pack. This diagnostic lists why each candidate was rejected; no candidate's ownership or borrowing effects are applied.

local type F = function(integer): string & function(string): boolean
local f: F = nil as any
return f(1)

Related: NUPP2006, NUPP2126. Reference: docs/learn/language/types/intersections.md#overload-selection. Open the reported program in the playground.

NUPP2126#

Several overloads accept a call.

local type F = function(integer): string & function(number): boolean
local f: F = nil as any
return f(1)

Overloads have no ranking or declaration-order tie breaker. A call must leave exactly one candidate; use distinguishable parameter packs or narrow an any argument before calling.

local type F = function(integer): string & function(string): boolean
local f: F = nil as any
return f(1)

Related: NUPP2125, NUPP2208. Reference: docs/learn/language/types/intersections.md#overload-selection. Open the reported program in the playground.

NUPP2127#

A declaration does not answer an associated type it is owed.

local interface Reader
    associated type Item
end

local record Lines is Reader
end

return Lines

An interface may state a type it does not name, and whatever takes that contract has to name it. A default on the interface answers it, so only a requirement nothing named is reported -- as is one that several contracts default differently, or that an implementor answers otherwise than a == equality fixes, since neither leaves one answer to take.

local interface Reader
    associated type Item
end

local record Lines is Reader
    associated type Item = string
end

return Lines

Related: NUPP2128, NUPP2116. Reference: docs/learn/language/types/associated-types.md#answering-a-requirement. Open the reported program in the playground.

NUPP2128#

An associated type member cannot mean anything where it is written.

local record Box
    associated type Item
end

return Box

An interface states a requirement, and = on one states a default. Anything else answers, so it needs the =, may not restate the bound -- what may answer is the contract's to say -- and may not use ==, which fixes a type on the contract that states it. Answering a name no contract declares means the name is private, which a plain nested type alias already is.

local record Box
    type Item = string
end

return Box

Related: NUPP2127, NUPP2117. Reference: docs/learn/language/types/associated-types.md#defaults-and-fixed-equalities. Open the reported program in the playground.

NUPP2129#

An associated type collides with another type member.

local interface Reader
    type Item = string
    associated type Item
end

return Reader

A declaration has one type namespace. An associated type and a nested alias or nested declaration share it, so two of a name is one namespace saying two things. Fields are a separate namespace and may share the spelling.

local interface Reader
    type Unit = string
    associated type Item
end

return Reader

Related: NUPP2128. Reference: docs/learn/language/types/associated-types.md#associated-types-are-not-nested-aliases. Open the reported program in the playground.

NUPP2130#

A type-level reduction cannot resolve the operator it is given.

local function read(value: {name: string}.['missing']): string
    return value
end

return read

keyof, T.[K], writeof, mapped shapes, and template construction each reduce a neutral type-level term to a concrete type. A term whose operand is not the shape the operator needs -- chief among them a member projection naming a key the subject does not have -- fails to reduce, and is reported where it was written rather than left as an opaque type.

local function read(value: {name: string}.['name']): string
    return value
end

return read

Related: NUPP2132, NUPP2133. Reference: docs/learn/language/types/comptime-types.md#direct-finite-operators. Open the reported program in the playground.

NUPP2131#

A const type parameter cannot be given the value it needs.

local function same<const S: string>(left: S, right: S): nil
end

same('x', 'y')

A const type parameter's value must be inferable from a use that names it directly -- an argument, or another const parameter already bound to the same one -- and every use inferring the same parameter must agree on exactly the same value. A parameter nothing binds, two arguments that disagree, or a value outside the parameter's declared const domain are each refused.

local function same<const S: string>(left: S, right: S): nil
end

same('x', 'x')

Related: NUPP2101, NUPP2130. Reference: docs/learn/language/types/comptime-types.md#const-parameters. Open the reported program in the playground.

NUPP2132#

A template type's hole cannot reduce to a finite string literal.

local function read(value: `${string}`): string
    return value
end

return read

A backtick template type's ${...} holes must each reduce to a finite union of string or numeric literals, so the product of every combination is itself finite. A hole naming an unbounded type such as string, or one that is not a valid compile-time constant expression at all, cannot be enumerated and is refused.

local type Choice = 'a' | 'b'
local function read(value: `${Choice}`): string
    return value
end

return read

Related: NUPP2130, NUPP2133. Reference: docs/learn/language/types/comptime-types.md#direct-finite-operators. Open the reported program in the playground.

NUPP2133#

A recursive type alias is not supported.

local type Loop<T> = Loop<T>
return Loop

Type aliases describe finite type expressions and cannot refer to themselves, directly or mutually. Write an ordinary recursive comptime function that returns type or typepack when the computation needs control flow.

@comptime
local function DeepElement(T: type): type
    while nupp.types.kind(T) == 'array' do
        T = nupp.types.elements(T)[1]
    end
    return T
end
local value: DeepElement({{integer}}) = 1
return value

Related: NUPP2130, NUPP2132. Reference: docs/learn/language/types/comptime-types.md#closed-and-generic-calls. Open the reported program in the playground.

NUPP2134#

A projection names something that cannot be projected.

local function first<T>(x: T): T.Item
    return nil as any
end

return first

T.Item is the associated type Item as whatever T answers it with, so it is a type only where some contract states that name. An unbounded binder has no contract to project through, a bounded one may not state the name, and a union states it only when every alternative does. A projection takes no type arguments.

local interface Reader
    associated type Item
end

local function first<T is Reader>(x: T): T.Item
    return nil as any
end

return first

Related: NUPP2127. Reference: docs/learn/language/types/associated-types.md#reaching-an-associated-type. Open the reported program in the playground.

NUPP2135#

An associated type answers through itself.

local interface Holds
    associated type Value
end

local record Direct is Holds
    associated type Value = Direct.Value
end

return Direct

An answer has to be a type that does not reach the member it answers. The graph is read once every answer and default is installed, so naming a member declared later in the body is ordinary and only a closed loop is reported. A cyclic default stays latent on the interface that states it and surfaces on the first concrete implementor.

local interface Holds
    associated type Value
end

local record Direct is Holds
    associated type Value = string
end

return Direct

Related: NUPP2127. Reference: docs/learn/language/types/associated-types.md#cycles-report-once-per-component. Open the reported program in the playground.

NUPP2136#

A sealed interface is implemented outside its owning module.

local spans = require("nupp.mem.span")

local record Forged is spans.Span<int32>
end

return Forged

A sealed interface carries hidden invariants that its public shape cannot prove. Only a declaration in the interface's own module may explicitly name it after is; structural lookalikes do not satisfy it. Obtain the value from that module's constructors instead of declaring another implementation.

local spans = require("nupp.mem.span")

local storage = ffi.new<int32[4]>()
local view = spans.fromFixedCarray(storage, 4)

return #view

Related: NUPP2001, NUPP2117. Reference: docs/learn/language/types/interfaces.md#sealed-interfaces. Open the reported program in the playground.

NUPP2137#

A switch pattern is not static or cannot bind what it names.

local n: integer = 2
local value = switch n do
    case 1 + 1 -> 'two'
    else -> 'other'
end
return value

Static switch cases are finite scalar literals or names whose checked type is one exact scalar. Type destructuring binds direct fields only, and every bound name and field must exist once in that arm.

local n: integer = 2
local value = switch n do
    case 2 -> 'two'
    else -> 'other'
end
return value

Related: NUPP2138, NUPP2140. Reference: docs/learn/language/switch-expressions.md#switch-expressions. Open the reported program in the playground.

NUPP2138#

A static switch value is handled more than once.

local n: number = 1
local value = switch n do
    case 1, 1.0 -> 'one'
    else -> 'other'
end
return value

Static cases compare Lua values, not source spellings. Numerically equivalent literals such as 1 and 1.0 are therefore duplicates.

local n: number = 1
local value = switch n do
    case 1 -> 'one'
    else -> 'other'
end
return value

Related: NUPP2137, NUPP2139. Reference: docs/learn/language/switch-expressions.md#switch-expressions. Open the reported program in the playground.

NUPP2139#

A switch case cannot be selected.

local n: 1 = 1
local value = switch n do
    case 2 -> 'two'
    else -> 'other'
end
return value

Cases are checked in source order against the selector type left by earlier cases. A value outside that type and an arm reached after the residue is empty are unreachable.

local n: number = 1
local value = switch n do
    case 2 -> 'two'
    else -> 'other'
end
return value

Related: NUPP2138, NUPP2140. Reference: docs/learn/language/switch-expressions.md#switch-expressions. Open the reported program in the playground.

NUPP2140#

A switch leaves possible selector values unhandled.

local type Mode = 'read' | 'write'
local mode: Mode = 'read'
local value = switch mode do case 'read' -> 1 end
return value

A switch is an expression and must produce a value whenever its selector returns. Cover every member of a finite checked type, or add else when the remaining set is open. A union declared with nupp.types.nonExhaustive() is always open, so it always needs else.

local type Mode = 'read' | 'write'
local mode: Mode = 'read'
local value = switch mode do
    case 'read' -> 1
    case 'write' -> 2
end
return value

Related: NUPP2139, NUPP2141. Reference: docs/learn/language/switch-expressions.md#switch-expressions. Open the reported program in the playground.

NUPP2141#

A do expression does not yield on every completing path.

local value = do local answer = 1 end
return value

A do expression produces one value with contextual yield value. Every path reaching its end must yield, and no statement may follow an unconditional yield in the same path. Return, break and continue retain their enclosing function or loop targets.

local value = do local answer = 1; yield answer end
return value

Related: NUPP2140, NUPP2142. Reference: docs/learn/language/do-expressions.md#do-expressions. Open the reported program in the playground.

NUPP2142#

A block expression is in an unsupported lowering position.

Do and switch expressions need a lexical statement context for their setup. The compiler reports positions its lowering cannot yet preserve. Bind the expression to a preceding local in the same conditional region when that preserves the intended evaluation order.

Related: NUPP2141. Reference: docs/learn/language/do-expressions.md#do-expressions.

NUPP2143#

An export carrying a runtime value sits beside export =.

module geom.shapes

local shapes = {}

export record Point
    x: number
end

export = shapes

A module either exports its declarations, and the compiler builds the table, or it names its value with export =, and that value is the module. A declaration that carries a runtime value cannot do both: there is no table of the compiler's for it to land on, and the named value is the author's to fill. Put it on that value instead. An interface or type alias is erased and stays legal beside one, because it contributes a type and no value.

module geom.shapes

local shapes = {}

record shapes.Point
    x: number
end

export = shapes

Related: NUPP2119. Reference: docs/learn/language/modules.md#migrating-a-table-shaped-module. Open the reported program in the playground.

NUPP2144#

An internal module is imported outside its package namespace.

A leading @!internal or an internal module segment restricts static imports to modules with the same first canonical namespace segment. An internal init.nupp restricts its descendants too. Import the package's public module instead. This applies to require, qualified values and qualified types; dynamic Lua loading remains unchecked and is not an access-control sandbox.

Reference: docs/learn/language/modules.md#internal-modules.

NUPP2145#

A type parameter conflicts with a builtin type name.

local record Box<string>
    value: string
end

return Box

Builtin type names always denote their primitive types in a type position. Using one for an ordinary generic parameter would create a parameter the declaration cannot refer to. Choose a name that is not a builtin type.

local record Box<T>
    value: T
end

return Box

Related: NUPP2101, NUPP2121. Reference: docs/learn/language/types/generics.md#parameter-positions. Open the reported program in the playground.

NUPP2146#

A generic declaration is applied to the wrong number of type arguments.

local record Pair<A, B>
    a: A
    b: B
end

local half: Pair<integer> = nil as any

return half

An application writes as many arguments as the declaration binds parameters. A trailing parameter the declaration defaulted may be left out; nothing past the last parameter may be written, and a bare name is an application with none. Left unchecked the result was a type whose parameters nothing had bound, which fits no value the program can build and surfaces instead as a mismatch between two types that print the same. Type<Box> and metatable<Box> name the declaration rather than one of its values and so take no arguments, and inside its own body a declaration means itself applied to its own parameters.

local record Pair<A, B>
    a: A
    b: B
end

local both: Pair<integer, string> = nil as any

return both

Related: NUPP2101, NUPP2116, NUPP2121. Reference: docs/learn/language/types/generics.md#instantiation. Open the reported program in the playground.

NUPP2147#

An is test's subject can never hold the type it tests.

local record Box
    value: integer
end

local function held(v: Box | string): boolean
    return not v is Box
end

return held

A test whose subject and its target share no value can only ever answer false, so the branch it guards is one no run reaches. It is refused where it is written rather than compiled. Only what can be settled for certain counts: any, a type parameter, and a structural fit the checker could not decide all leave the test alone, and as remains the way to say the value is something its declaration does not admit. is sits at the comparison level, below unary not, so not v is T is (not v) is T -- a boolean tested for the identity of something else -- and not (v is T) is the test that narrows.

local record Box
    value: integer
end

local function held(v: Box | string): boolean
    return not (v is Box)
end

return held

Related: NUPP2110, NUPP3001. Reference: docs/learn/language/types/narrowing.md#type-tests. Open the reported program in the playground.

NUPP2148#

A result type parameter cannot be inferred.

local function make<T>(): T
    error('not reached')
end

local value = make()

return value

A type or type-pack parameter used by a call's result needs evidence from an explicit type argument, an argument value, a destination type, an any input, or a declared default. Without any of those, substituting any would silently erase the result's type. A parameter absent from the result does not need evidence.

local function make<T>(): T
    error('not reached')
end

local value = make<string>()

return value

Related: NUPP2116, NUPP2131, NUPP2146. Reference: docs/learn/language/types/generics.md#inference-at-a-call-site. Open the reported program in the playground.

NUPP2149#

An operand's results cannot be read by an exit suffix.

local function name(): string
    return "x"
end
local function first(): string?
    local value = name() or return
    return value
end
return first()

or return, or break and or continue read the operand's first result as both the discriminator and the value. That needs a fixed result count, results that are not a correlated pack union, and a first result that can be nil or false and can also be a value. pcall and xpcall are refused by the union rule, because they lead with the discriminator rather than with a result; nupp.util.try and nupp.util.tryWith answer the conventional order instead.

local function name(): string?
    return "x"
end
local function first(): string?
    local value = name() or return
    return value
end
return first()

Related: NUPP2002, NUPP2605. Reference: docs/learn/language/exit-suffixes.md#exit-suffixes. Open the reported program in the playground.

NUPP2201#

A struct field has no C-representable layout.

local struct Loop
    me: Loop
    n: int32
end
return Loop

A struct is laid out in C memory, so every field needs a fixed size and offset. A field type has to be reifiable: a numeric primitive, another struct held by value, a pointer, or a fixed C array. A struct cannot hold itself by value, because the layout would then have to contain a copy of itself and so would have no size; hold self-reference through a pointer instead.

local struct Loop
    me: Loop*?
    n: int32
end
return Loop

Related: NUPP2204, NUPP2205, NUPP2402. Reference: docs/learn/language/types/records-and-structs.md#pointing-at-itself. Open the reported program in the playground.

NUPP2202#

A declaration is built with 'new'.

local record Point
    x: integer
end

local p = Point{x = 1}

return p

Records and structs are constructed with new, so calling a declaration is never a construction and the call stays the program's own: a record's __call is not shadowed when the argument is a table, and a struct's ctype call is not claimed. A record that does declare a __call contract is called, not reported.

local record Point
    x: integer
end

local p = new Point(x = 1)

return p

Related: NUPP2206. Reference: docs/learn/language/types/records-and-structs.md#records. Open the reported program in the playground.

NUPP2203#

A C declaration uses a type C cannot represent.

cdef function process(values: {number}): int32
return process

A cdef signature and struct layout cross the C ABI, so their types must have a C representation. Lua tables, records, and other garbage-collected values need an explicit pointer or handle boundary.

cdef function process(values: voidptr): int32
return process

Related: NUPP2201, NUPP2602. Reference: docs/learn/runtime/c-interop/index.md#hand-write-a-small-binding. Open the reported program in the playground.

NUPP2204#

A struct declares a Lua array part.

local struct P
    {integer}
    x: float
end
return P

The array part {T} makes a record's own instances behave as a one-based Lua sequence, which only makes sense for a table-backed value. A struct has no Lua table underneath it, so it cannot declare one; use a fixed C array field T[N] for an inline vector instead.

local struct P
    x: float[4]
end
return P

Related: NUPP2201, NUPP2205. Open the reported program in the playground.

NUPP2205#

An array part is not written as a single element type.

local record R
    {x: integer}
    y: integer
end
return R

The array part is spelled {T}: braces around exactly the element type. Anything else inside the braces, such as a shape with named fields, resolves to a different kind of type and is not a valid array part.

local record R
    {integer}
    y: integer
end
return R

Related: NUPP2204, NUPP2201. Open the reported program in the playground.

NUPP2206#

Only a record or a struct can be constructed.

local interface Named
    name: string
end

local n = new Named(name = "ada")

return n

new names a type and builds a value of it, so the operand has to be a declaration with something to build. An interface declares a contract and has no runtime table to stamp; an enum value is one of its declared strings, written directly. The operand is answered as a type rather than through whatever value stands under the name, because an interface binds none.

local interface Named
    name: string
end

local record User is Named
    name: string
end

local n = new User(name = "ada")

return n

Related: NUPP2202. Reference: docs/learn/language/types/records-and-structs.md#records. Open the reported program in the playground.

NUPP2207#

A binding is read before it holds a value.

local record Point
    x: integer
end

local p: Point

return p.x

local v: Vec2 declares a binding and constructs nothing, so the binding holds nil until something assigns to it, and reading it before that indexes nil at run time rather than yielding a value of the declared type. The checker holds every annotation that does not admit nil to this, and a binding is assigned only once every path reaching the read assigned it: an assignment on one arm of an if, or inside a loop that may not run, is not one. Assign it first, or declare it optional if it is meant to start empty. A declaration file states what exists elsewhere and assigns nothing, so it is exempt.

local record Point
    x: integer
end

local p: Point = new Point(x = 0)

return p.x

Related: NUPP2202, NUPP2206. Reference: docs/learn/language/types/records-and-structs.md#records. Open the reported program in the playground.

NUPP2208#

A constructor does not hold up its declaration.

local record Account
    name: string
    balance: number

    constructor(self, name: string)
        self.name = name
    end
end

return Account

A constructor(self, ...) body is what new T(...) runs. The instance is made before it and returned after it, so its whole job is to fill the fields in, and every field that cannot hold nil has to be filled, or the value handed back does not match the declaration it claims. That guarantee is the reason to prefer a constructor over a literal, so declaring one closes the literal form for that declaration. An interface builds nothing and cannot carry one. Constructors may be overloaded by parameter pack. A result annotation is the successful construction policy: it must be one value that erases to the record itself, such as affine(T, T.destroy), because the body still returns the instance it allocated.

local record Account
    name: string
    balance: number

    constructor(self, name: string)
        self.name = name
        self.balance = 0
    end
end

return Account

Related: NUPP2202, NUPP2207. Reference: docs/learn/language/types/records-and-structs.md#constructors-and-result-policies. Open the reported program in the playground.

NUPP2209#

A private record field is used outside its module.

local h = require('nupp.mem.heap')
local a = h.allocate(ffi.typeof<int32>(), 1)
return a.pointer

A private field is representation available only while checking the canonical module that declares its record. Expose a public method when another module needs an operation without revealing that representation.

local h = require('nupp.mem.heap')
local a = h.allocate(ffi.typeof<int32>(), 1)
return a:read()[1]

Related: NUPP2004, NUPP2202. Reference: docs/learn/language/types/records-and-structs.md#private-fields. Open the reported program in the playground.

NUPP2301#

cheader's arguments are not the literal form it takes.

local mini = cheader("mini" .. ".h")
return mini

cheader reads the named header at compile time, so everything it is given has to be known to the compiler before the program runs. It takes a literal header path, then optionally a literal library name, then optionally the literal "preprocess", and nothing more. A computed header path or library name, a third argument other than "preprocess", and any argument after the third are each refused.

local mini = cheader("mini.h")
return mini

Related: NUPP2302. Reference: docs/learn/runtime/c-interop/index.md#type-the-header-in-place. Open the reported program in the playground.

NUPP2302#

A cheader path cannot be read.

local mini = cheader("missing.h")
return mini

cheader resolves its literal path relative to the file, then as written, then against each project root, and reads whichever candidate exists first. When none can be opened, the diagnostic reports why, the same way an unreadable source path is reported.

Related: NUPP2301, NUPP0001. Reference: docs/learn/runtime/c-interop/index.md#type-the-header-in-place. Open the reported program in the playground.

NUPP2303#

A literal ffi.cdef block does not parse as C.

local ffi = require("ffi")
ffi.cdef[[ this is not C ]]
return 0

A literal string given directly to ffi.cdef declares to the checker as well as to LuaJIT at runtime, so it has to be declarations LuaJIT's own C parser accepts. A string built at runtime, or reached only through a guard, is not read this way and so cannot be checked.

local ffi = require("ffi")
ffi.cdef[[ int mini_add(int a, int b); ]]
return 0

Related: NUPP2301, NUPP2304. Reference: docs/learn/runtime/c-interop/index.md#hand-write-a-small-binding. Open the reported program in the playground.

NUPP2304#

A typed FFI operation's type string does not name a C type.

local ffi = require("ffi")
ffi.cdef[[ struct CstA { int x; }; ]]
local p = ffi.new("struct CstNoSuch")
return p

ffi.new, ffi.cast, ffi.typeof, ffi.istype, ffi.sizeof, and ffi.alignof read a literal string argument through LuaJIT's own type-string parser when one is given, so that string has to name a type already declared, through a cdef or cheader the checker has already seen.

local ffi = require("ffi")
ffi.cdef[[ struct CstA { int x; }; ]]
local p = ffi.new("struct CstA")
return p

Related: NUPP2303, NUPP2203. Reference: docs/learn/runtime/c-interop/index.md#typed-ffi-operations. Open the reported program in the playground.

NUPP2401#

carray's arguments are not a struct type and an element count.

local record Point
    x: number
    y: number
end

local points = carray(Point, 4)
return points

carray(T, n) allocates a zero-based C array of n elements of T. T must resolve to a reified struct type -- a record is a table with no C layout to array up -- and n must be a number, or any, usable as an element count.

local struct Point
    x: float
    y: float
end

local points = carray(Point, 4)
return points

Related: NUPP2402, NUPP2201. Reference: docs/learn/runtime/c-interop/index.md#typed-ffi-operations. Open the reported program in the playground.

NUPP2402#

layoutof was asked about something with no C layout.

local record Point
    x: number
    y: number
end

return layoutof(Point)

layoutof(T) answers how a reified struct sits in memory: its fields in declaration order with their offsets, sizes and padding, the whole size, and a fingerprint over all of it. Only a struct has one -- a record is a table, not C memory -- and a struct with no fields has nothing to lay out.

local struct Point
    x: float
    y: float
end

return layoutof(Point)

Related: NUPP2401, NUPP2201. Reference: docs/learn/runtime/c-interop/index.md#read-a-structs-layout. Open the reported program in the playground.

NUPP2403#

An SoA allocation or column projection has no resolved stored field.

local soa = require("nupp.mem.soa")
local ffi = require("ffi")

local rows = soa.allocate(ffi.typeof<int32>(), 4)
return rows

Structure-of-arrays storage accepts only a reified struct whose top-level fields have fixed C storage; a record, union, interface, GC-managed field, owned field, borrowed field, or variable-size field is not SoA-eligible. A row view's dot or literal bracket projection must likewise name one such stored field of that struct, not a dynamic name or an unknown one.

local soa = require("nupp.mem.soa")
local ffi = require("ffi")

local struct Point
    x: float
    y: float
end

local rows = soa.allocate(ffi.typeof<Point>(), 4)
rows:close()

Related: NUPP2402, NUPP2009. Open the reported program in the playground.

NUPP2410#

A comptime block reads or writes a binding it cannot reach.

local n = 5
local value: integer = comptime do
    return n
end
print(value)

A comptime block evaluates in a scope of its own: its own locals and parameters, comptime-declared functions, and the allowlisted compile-time environment. A runtime local, upvalue, module-level binding, global, or an ambient library the environment does not expose -- io, os, require, debug among them -- cannot be read, and the same set cannot be assigned.

local value: integer = comptime do
    return 5
end
print(value)

Related: NUPP2411, NUPP2412. Open the reported program in the playground.

NUPP2411#

A construct or library member is unavailable at comptime.

local value: number = comptime do
    return math.random()
end
print(value)

The comptime evaluator supports a fixed subset of Nupp -- literals, control flow, operators over ordinary values, and calls into an explicit allowlist of library members -- and names what falls outside it: a nested function declaration, a multi-value result, a logical operator observing an opaque value, or a library member the allowlist leaves out because it is nondeterministic, such as math.random.

local value: number = comptime do
    return math.floor(7 / 2)
end
print(value)

Related: NUPP2410, NUPP2412. Open the reported program in the playground.

NUPP2412#

A comptime evaluation exceeded a bound or used a value it cannot.

local value: string = comptime do
    return tostring({})
end
print(value)

Comptime evaluation is bounded so a block always finishes, and defined only over values its operations actually support: a step count, a helper call's frame depth, and an allocation size are each checked against a fixed limit, a comptime function must return and must be called with the argument count its parameters declare, and indexing, calling, or printing a value in a way its runtime kind does not support fails the same way.

local value: string = comptime do
    return tostring(5)
end
print(value)

Related: NUPP2410, NUPP2411. Open the reported program in the playground.

NUPP2413#

A comptime result has no literal spelling.

local value: {{integer}} = comptime do
    local shared = {1}
    return {shared, shared}
end
print(value)

A block's result is quoted into the generated Lua as a literal: nil, booleans, numbers that read back unchanged, strings, and acyclic tables of those with no metatable. NaN, the infinities, functions, and cdata have no such spelling, and a table reachable by more than one path is refused rather than quoted twice into two tables where the block built one.

local value: {{integer}} = comptime do
    return {{1}, {1}}
end
print(value)

Related: NUPP2414, NUPP2416. Reference: docs/learn/language/comptime.md#values-checked-at-their-destination. Open the reported program in the playground.

NUPP2414#

An opaque comptime result did not reach a materialization boundary.

local record Position
    x: number
    y: number
end

const codec = comptime do
    return nupp.reflect.fieldCodec(nupp.reflect(Position))
end

print(codec)

A sealed provider -- reflection's field-codec builder among them -- may return a description with no literal spelling. It materializes only when the comptime block directly initializes a declaration whose annotated type the provider owns; an inferred binding, or an opaque value nested inside an ordinary table, gives it nowhere to materialize into.

local record Position
    x: number
    y: number
end

const codec: nupp.reflect.FieldCodec<Position> = comptime do
    return nupp.reflect.fieldCodec(nupp.reflect(Position))
end

print(codec)

Related: NUPP2415, NUPP2416. Reference: docs/learn/language/reflection.md#comptime-reflection. Open the reported program in the playground.

NUPP2415#

A comptime-only value failed validation where it landed.

@comptime
local function answer(): integer return 42 end
local escaped = answer
return escaped()

A comptime function's own identity, a type or const-function argument crossing into the isolated comptime worker, and an opaque provider result reaching a materialization boundary are all checked against exactly where they land. A comptime function read as an ordinary runtime value has nowhere to run there, an argument that cannot import into the worker cannot be evaluated, and a declared type with no registered materialization relation for what a provider produced cannot receive it.

@comptime
local function answer(): integer return 42 end
return comptime do return answer() end

Related: NUPP2414, NUPP2416. Open the reported program in the playground.

NUPP2416#

A comptime result or worker message exceeds its bound.

return comptime do
    local values = {}
    for index = 1, 12000 do values[index] = index end
    return values
end

Comptime evaluation runs in an isolated worker with fixed step, memory, and result-graph limits, and talks to the compiler over a bounded protocol. A finalized value graph over the item limit, and a worker request or response over the protocol byte limit, are reported here instead of being silently truncated or left to crash the worker.

return comptime do
    local values = {}
    for index = 1, 10 do values[index] = index end
    return values
end

Related: NUPP2415, NUPP2412. Open the reported program in the playground.

NUPP2417#

A PEG intrinsic call or finalized grammar is malformed.

const Bad: nupp.peg.Peg<integer> = comptime do
    return nupp.peg.compile("('')*")
end
return Bad

Every nupp.peg intrinsic is checked against the pattern arguments it needs, and a finalized grammar is checked against PEG's own rules once assembled. Repetition is possessive and must consume at least one byte whenever it succeeds, so a nullable repetition such as ('')* is refused, and direct or indirect left recursion is refused because a top-down parser cannot re-enter a rule at the position it started.

const Good: nupp.peg.Peg<integer> = comptime do
    return nupp.peg.compile("('x')*")
end
return Good

Related: NUPP2415, NUPP2416. Open the reported program in the playground.

NUPP2418#

nupp.reflect was applied to something other than a resolvable type.

local value = 1
const Bad: nupp.reflect.FieldCodec<any> = comptime do
    return nupp.reflect.fieldCodec(nupp.reflect(value))
end
return Bad, value

nupp.reflect(T) resolves T in type position; it does not accept an expression that merely holds a runtime value, or one that fails to name a type at all. nupp.reflect.fieldCodec further requires that descriptor to describe a record, since only a record has present declared fields for the codec to copy.

local record Item
    value: integer
end
const Good: nupp.reflect.FieldCodec<Item> = comptime do
    return nupp.reflect.fieldCodec(nupp.reflect(Item))
end
return Good

Related: NUPP2415, NUPP2416. Open the reported program in the playground.

NUPP2419#

A layout intrinsic has no target, a bad shape, or an unknown field.

local struct Value
    n: int32
end
return comptime do return nupp.sizeof(Value) end

nupp.sizeof, nupp.alignof, and nupp.offsetof run only inside a comptime block, against the actual nupp global, with one concrete type argument (plus a compile-time-known field name for offsetof). Once the call's shape is right, it still needs the selected build's layoutTarget configured and a type with a runtime C layout to measure; a record or an unmodeled type has none. A program that only needs the host's own layout should measure it at runtime with ffi.sizeof instead.

local struct Value
    n: int32
end
local size = ffi.sizeof<Value>()
return size

Related: NUPP2410, NUPP2416. Open the reported program in the playground.

NUPP2420#

A comptime type function rejected its own application.

@comptime
local function Positive(): type
    return nupp.types.error("always fails")
end
local value: Positive() = 1
return value

nupp.types.error(message) lets a comptime type function refuse a specific application deliberately, distinct from an evaluator crash or a result of the wrong kind. The authored message is reported at the application together with the bounded comptime call trace, so a computed type contract can say why an argument it inspected does not qualify.

@comptime
local function Positive(): type
    return nupp.types.number
end
local value: Positive() = 1
return value

Related: NUPP2415, NUPP2421. Reference: docs/learn/language/types/comptime-types.md#inspection-and-construction. Open the reported program in the playground.

NUPP2421#

A compiler-only member or type-position call was used where it cannot run.

local leaked = nupp.types.string
return leaked

Type handles, comptime type aliases, and members typed comptime type or @comptime function(...) are opaque and exist only for the comptime evaluator. Reading one into an ordinary runtime binding, naming a comptime alias in a runtime annotation, or writing a type-position call whose callee, argument, or result does not resolve to a checked comptime function signature is refused because none has anything to erase to at runtime.

@comptime
local function Self(): type
    return nupp.types.string
end
local value: Self() = "ok"
return value

Related: NUPP2133, NUPP2420. Reference: docs/learn/language/types/comptime-types.md#inspection-and-construction. Open the reported program in the playground.

NUPP2422#

A constrained type declaration names an unsupported base or empty bounds.

local type Empty = nupp.types.range(integer, 10, 0)
local value: Empty = 5
return value

nupp.types.range narrows integer, int32 or uint32, and nupp.types.length narrows string; either may also narrow a constrained alias of one, which intersects the two constraints. Both bounds are inclusive whole numbers in ascending order, and both must lie inside what the base itself admits, so a declaration that admits nothing is reported where it is written rather than compiled into a test no value passes.

local type Small = nupp.types.range(integer, 0, 10)
local value: Small = 5
return value

Related: NUPP2013, NUPP2421. Open the reported program in the playground.

NUPP2501#

A cast to a C pointer type has no lifetime root to hold the string alive.

local pointer = ffi.cast<cstring>('a' .. 'b')
print(pointer)

The string-pointer lint reports a ffi.cast<T>(value) to a pointer type whose argument is a Lua string but is not itself a named binding or a preserved parameter: the pointer aliases the string's bytes, and a fresh string is scratch storage LuaJIT is free to collect once the expression that produced it goes unread. Bind the string to a local, or thread it through a preserving parameter, before casting a pointer out of it. Default level is warning, and a project may reconfigure or suppress it like any other lint.

local text = 'a' .. 'b'
local pointer = ffi.cast<cstring>(text)
print(pointer)

Reported by the string-pointer lint, category suspicious, at warning by default. Configure it by name or by category.

Related: NUPP2608, NUPP2603. Reference: docs/reference/lints.md#string-pointer. Open the reported program in the playground.

NUPP2502#

A Lua function is cast to a C callback.

@unsafe do
    local callback = function()
    end
    local pointer = ffi.cast<voidptr>(callback)
    local handle = nupp.pin(pointer, callback)
end

The jit-callback lint reports a cast of a Lua function to a C-derived callback type. The cast requires @unsafe permission and an explicit retained owner, but LuaJIT registers the function as a permanent C callback once it happens, and no trace can compile through that call boundary for as long as it stays registered. Call jit.off on the registering function when the callback is intentional, or pass a plain pointer instead. Default level is warning, and a project may reconfigure or suppress it like any other lint.

@unsafe do
    local pointer = ffi.cast<voidptr>(8)
    print(pointer)
end

Reported by the jit-callback lint, category suspicious, at warning by default. Configure it by name or by category.

Related: NUPP2604, NUPP2603. Reference: docs/reference/lints.md#jit-callback. Open the reported program in the playground.

NUPP2504#

An operator uses its customary C-style spelling.

local ready = true
local pending = !ready
return pending

The C-style spellings !, &&, ||, and != are accepted, but the style lint prefers Lua's not, and, or, and ~=. The spelling changes; the expression's meaning does not.

local ready = true
local pending = not ready
return pending

Reported by the customary-operator lint, category style, at warning by default. Configure it by name or by category.

Related: NUPP2108. Reference: docs/reference/lints.md#customary-operator. Open the reported program in the playground.

NUPP2505#

A loop builds the same non-capturing function on every iteration.

local function register(item: any, callback: function(): boolean): nil
    print(item, callback())
end

local function run(items: {any}): nil
    for _, item in ipairs(items) do
        register(item, function(): boolean
            return true
        end)
    end
end

return run

The loop-invariant-closure lint reports a function literal built inside a loop body that reads nothing from the iteration, so every built copy is the same function and building one afresh each time buys nothing. LuaJIT has no recorder for the bytecode that builds a function, so a loop containing one aborts trace recording every time it is tried and is eventually blacklisted, running interpreted from then on however hot it gets. Declare the function once above the loop and pass its name. Default level is warning; the sibling jit-loop-closure reports the case where the function does read the iteration and cannot be lifted.

local function register(item: any, callback: function(): boolean): nil
    print(item, callback())
end

local function alwaysTrue(): boolean
    return true
end

local function run(items: {any}): nil
    for _, item in ipairs(items) do
        register(item, alwaysTrue)
    end
end

return run

Reported by the loop-invariant-closure lint, category suspicious, at warning by default. Configure it by name or by category.

Related: NUPP2515, NUPP2707. Reference: docs/reference/lints.md#loop-invariant-closure. Open the reported program in the playground.

NUPP2506#

A documented function can raise without saying when.

--- Reads a name.
--- @param name the name to read
local function read(name: string): string
    if name == "" then error("empty name") end
    return name
end

return read

A function with a docblock that calls error must document the condition with @raises Type the condition. Callers reading generated documentation then see the exceptional exit, and what it hands back, beside the ordinary result.

--- Reads a name.
--- @param name the name to read
--- @raises string when name is empty
local function read(name: string): string
    if name == "" then error("empty name") end
    return name
end

return read

Reported by the undocumented-raise lint, category suspicious, at warning by default. Configure it by name or by category.

Related: NUPP1010, NUPP2507. Reference: docs/reference/lints.md#undocumented-raise. Open the reported program in the playground.

NUPP2507#

A local is declared and nothing reads it.

local function shout(text: string): string
    local prefix = "> "
    return text .. "!"
end

return shout

A binding nothing reads is a leftover from an edit, or a use that went to another name. Delete it, or name it _ when the value is deliberately not wanted. A parameter and a loop variable are bound by a signature and an iterator rather than by their author, so neither is judged.

local function shout(text: string): string
    local prefix = "> "
    return prefix .. text .. "!"
end

return shout

Reported by the unused-binding lint, category suspicious, at warning by default. Configure it by name or by category.

Related: NUPP2120, NUPP2603. Reference: docs/reference/lints.md#unused-binding. Open the reported program in the playground.

NUPP2508#

A call that does nothing but return had its result dropped.

local function double(value: number): number
    return value * 2
end

double(21)

return double

A call written as a statement is made for what it does. When the callee is proved to do nothing but produce a value, and the statement drops that value, the whole statement does nothing. Use the result, or delete the call.

local function double(value: number): number
    return value * 2
end

local answer = double(21)
print(answer)

return double

Reported by the discarded-result lint, category suspicious, at warning by default. Configure it by name or by category.

Related: NUPP2112, NUPP2603. Reference: docs/reference/lints.md#discarded-result. Open the reported program in the playground.

NUPP2509#

A record's fields would all fit in C memory.

The reifiable-record lint reports a record declaration whose every member -- fields, constructors, methods -- is one a struct would also accept: every field's type reifies, and nothing else in the body (an indexer, a Lua array part, a declaration-only metamethod, a nested declaration, a property capability, generics, or a declared supertype) rules struct out. Declaring it struct instead moves instances into C memory, off the collector's graph, at the cost of a fixed layout and giving up pairs/table-serializer support without an explicit hook. This is a suggestion rather than a correctness rule, so it defaults to off; a project turns it on with lints = {["reifiable-record"] = "note"} or by raising the whole performance category.

Reported by the reifiable-record lint, category performance, at off by default. Configure it by name or by category.

Related: NUPP2201, NUPP2012. Reference: docs/reference/lints.md#reifiable-record.

NUPP2510#

An else contains only a nested if.

local function classify(primary: boolean, fallback: boolean): nil
    if primary then
        print("primary")
    else
        if fallback then
            print("fallback")
        end
    end
end

return classify

The else-if lint reports an else block whose only statement is an unannotated if, which is the long way to write elseif; it also recognizes adjacent if statements that compare the same local to different literals when the first body does not reassign it. Write elseif (or fold the adjacent ifs into one chain) so the chain reads as one dispatch rather than nested blocks. Default level is warning, and a project may reconfigure or suppress it like any other lint.

local function classify(primary: boolean, fallback: boolean): nil
    if primary then
        print("primary")
    elseif fallback then
        print("fallback")
    end
end

return classify

Reported by the else-if lint, category style, at warning by default. Configure it by name or by category.

Related: NUPP2107. Reference: docs/reference/lints.md#else-if. Open the reported program in the playground.

NUPP2511#

An associated type was erased because inference did not reach its head.

local interface Holds
    associated type Item
end

local function held<T is Holds>(x: T): T.Item
    return nil as any
end

local erased = held(nil as any)

return erased

A projection is checked as any when inference never worked out what answers it, which is the feature declining to say anything rather than saying the call is right. Reported once per call and member, where the erasure happened, because a parameter erased that way accepts whatever it is given.

local interface Holds
    associated type Item
end

local record Lines is Holds
    associated type Item = string
end

local function held<T is Holds>(x: T): T.Item
    return nil as any
end

local kept = held(new Lines())

return kept

Reported by the erased-projection lint, category suspicious, at warning by default. Configure it by name or by category.

Related: NUPP2134. Reference: docs/learn/language/types/associated-types.md#erased-projections. Open the reported program in the playground.

NUPP2512#

A record is built by field order rather than by naming its fields.

local record Point
    x: integer
    y: integer
end

local p = new Point(1, 2)

return p

A record without a declared constructor may be built either way, and both build the same table. Naming the fields says at the call site which value lands where; leaving it to the order says it in the declaration, so a reader has to go there, and adding a field silently changes what an existing call means. A struct is exempt: it is its C layout, and that order is the layout's rather than the program's to name. Turn it off by name or by its style category, or write @allow("positional-record-construction").

local record Point
    x: integer
    y: integer
end

local p = new Point(x = 1, y = 2)

return p

Reported by the positional-record-construction lint, category style, at warning by default. Configure it by name or by category.

Related: NUPP2202, NUPP2208. Reference: docs/reference/lints.md#positional-record-construction. Open the reported program in the playground.

NUPP2513#

An API marked deprecated is used.

local function current(): integer return 1 end

@deprecated(replacement = "current")
local function legacy(): integer return current() end

return legacy()

@deprecated keeps an API available while telling callers to move away from it. The optional reason explains why and the replacement names what to use instead. The annotation changes tooling only: it reports this suppressible lint at use sites and emits no runtime behavior.

local function current(): integer return 1 end

@deprecated(replacement = "current")
local function legacy(): integer return current() end

return current()

Reported by the deprecated lint, category suspicious, at warning by default. Configure it by name or by category.

Related: NUPP2115. Reference: docs/reference/lints.md#deprecated. Open the reported program in the playground.

NUPP2514#

A variadic FFI call is reachable from a compiled trace.

cdef function printf(format: cstring, ...): int32

local function report(value: int32): nil
    printf("%d", value)
end

return report

The jit-boundary lint reports a call to a cdef function declared with a ... variadic tail from code LuaJIT may try to compile: a variadic C call cannot safely execute on a trace. Move the call into a helper disabled with jit.off, so the interpreter always runs it, rather than leaving the boundary reachable from hot code. Default level is warning; inside an @jit function the same boundary is instead the non-suppressible NUPP2707 contract error.

cdef function printf(format: cstring, ...): int32

local function coldReport(value: int32): nil
    printf("%d", value)
end
jit.off(coldReport)

local function report(value: int32): nil
    coldReport(value)
end

return report

Reported by the jit-boundary lint, category suspicious, at warning by default. Configure it by name or by category.

Related: NUPP2707, NUPP2502. Reference: docs/reference/lints.md#jit-boundary. Open the reported program in the playground.

NUPP2515#

A loop builds a function and so never compiles.

LuaJIT has no recording for the bytecode that builds a function, so a loop containing one aborts trace recording, is blacklisted after enough attempts, and then runs interpreted however hot it gets. A function that reads nothing from the iteration is loop-invariant-closure and lifts out unchanged; this is the other one, which reads the iteration and cannot. The way out where there is one is to declare a function above the loop that takes what varies as arguments, so the loop calls one rather than builds one.

Nothing about the program's answers changes either way, which is why this is off until a project asks for it. @jit is where it is not optional: that annotation promises the function compiles, so the same hazard inside one is reported as NUPP2707, and jit.off on the enclosing function silences it. nupp bc --check finds the same loops in any file without running it.