Every test in this post ran on 2026-11-18. Disclosure: I'm on the UnAIMyText team and I picked its #3 spot in the tool list myself. The script is yours to copy and change.
Search LuaRocks for anything popular and you'll find rockspecs whose one-line summary looks like this:
This library provides a blazing fast, robust and seamless way to parse CSV files in Lua.
That's 88 characters of adjectives with a period at the end, and it's what the search results page shows next to your package name. A friend's team had a dozen rocks like that, most of them generated by asking a model to "write the rockspec." Some also had license = "MIT License" and a homepage pointing at a release tarball.
So I wrote a linter for the description table. It's one Lua file. With --draft it sends the rockspec to a model on Novita AI, asks for a summary and a detailed, and lints the reply before you commit it.
What LuaRocks actually asks for
The rockspec format docs are short and specific about the description table:
-
summaryis a one-line description of the package. Their example: "Network support for the Lua language." -
detailedis the longer description. -
licenseshould be a short name like "MIT" or "GPL-2". -
homepageis the project's website, not the URL of the tarball. -
labels(since 3.0) is a list of short strings for categorization.
That example summary is the whole style guide in seven words: a noun phrase that says what the thing does. Models produce the opposite. They write a sentence about how powerful the library is.
The Novita part
Novita's LLM API guide says the API is OpenAI-compatible: set the base URL to https://api.novita.ai/openai and post to /v1/chat/completions with Authorization: Bearer <key>. The script defaults to deepseek/deepseek-v4.1-flash, the model in that guide's examples; set NOVITA_MODEL to anything from the current model list. Their chat completion reference describes response_format: {"type": "json_object"} as the older JSON mode, which is enough here since I only want two string fields back.
With a fake key the real endpoint returns 401 and FAILED_TO_AUTH. With no header, 403 and INVALID_API_KEY. The script exits 2 and prints the body for both.
Why Lua?
A rockspec is a Lua file, so the cleanest way to read one is to run it. The script calls load(src, name, "t", env) with an empty table as the environment. Assignments like description = { ... } land in that table, and the rockspec can't reach os, io or require. One of my test rockspecs calls os.execute; it fails with "attempt to index a nil value (global 'os')" and nothing runs.
Two practical notes:
- JSON comes from dkjson (
luarocks install dkjson), a single pure-Lua file. - Lua has no HTTP client in the standard library, so the script shells out to
curl. The key goes into a file fromos.tmpname(), which on POSIX builds usesmkstempand creates it0600; curl reads it with-H @fileand the file is deleted right after. The key never shows up inps.
What it checks
In description:
-
summarymissing, empty or more than one line -
summarylonger than 80 characters (my number, not LuaRocks') - Ends with a full stop
- Reads like a sentence: starts with "This", or "A"/"An" followed later by "that"
- Only repeats the package name (
tinyiniintinyini-1.0-1.rockspec) or starts with "name is" - Generic words such as
blazing,robust,seamless,state-of-the-art,high-performance - Chatbot words (
delve,leverage,empower,harness) and openers ("In today's", "Unlock", "Introducing") insummaryordetailed - Emoji
-
detailedidentical tosummary -
licensewritten out as "MIT License" instead of a short name -
homepagethat isn't http(s), or that ends in.tar.gz,.zipor.rock -
labelsthat isn't a list of strings
It exits 0 when everything is fine and 1 when it found something. Exit 2 covers the rest: bad usage, a rockspec that won't load, curl failing, a non-200 status, or a reply with no usable JSON.
The linter
#!/usr/bin/env lua
-- rockdesc.lua - lint the description table of LuaRocks rockspecs,
-- or ask a model on Novita AI to draft one and lint the draft.
local json = require("dkjson")
local MAX_SUMMARY = 80 -- house rule, not a LuaRocks limit
local GENERIC = { "blazing", "robust", "seamless", "seamlessly", "powerful",
"cutting-edge", "state-of-the-art", "next-generation", "comprehensive",
"elegant", "versatile", "effortless", "game-changing", "world-class",
"high-performance" }
local AI_OPENERS = { "in today's", "introducing", "unlock", "whether you're",
"say goodbye", "look no further", "elevate" }
local AI_WORDS = { "delve", "leverage", "leverages", "empower", "empowers",
"harness", "tapestry", "supercharge", "unleash" }
local function has_word(text, word)
-- %f frontier patterns act as word boundaries; escape magic chars like "-"
local w = word:gsub("%p", "%%%0")
return text:lower():find("%f[%w]" .. w .. "%f[%W]") ~= nil
end
local function lint_text(field, s, pkg, out)
local low = s:lower()
for _, w in ipairs(GENERIC) do
if has_word(low, w) then out[#out + 1] = field .. ": generic word '" .. w .. "'" end
end
for _, w in ipairs(AI_WORDS) do
if has_word(low, w) then out[#out + 1] = field .. ": chatbot word '" .. w .. "'" end
end
for _, o in ipairs(AI_OPENERS) do
if low:sub(1, #o) == o then out[#out + 1] = field .. ": opens with '" .. o .. "'" end
end
if s:find("[\240-\244]") then out[#out + 1] = field .. ": contains an emoji" end
end
local function lint_desc(d, pkg)
local out = {}
if type(d) ~= "table" then return { "no description table" } end
local s = d.summary
if type(s) ~= "string" or s:match("^%s*$") then
out[#out + 1] = "summary: missing or empty"
else
if s:find("\n") then out[#out + 1] = "summary: more than one line" end
if #s > MAX_SUMMARY then out[#out + 1] = ("summary: %d chars (max %d)"):format(#s, MAX_SUMMARY) end
if s:match("%.%s*$") then out[#out + 1] = "summary: ends with a full stop" end
local first = s:match("^%s*(%S+)") or ""
local fl = first:lower()
if fl == "this" or ((fl == "a" or fl == "an") and s:lower():find("%f[%w]that%f[%W]")) then
out[#out + 1] = "summary: reads like a sentence ('" .. first .. " ...')"
end
if pkg and (s:lower() == pkg:lower() or s:lower():find("^" .. pkg:lower():gsub("%p", "%%%0") .. " is ")) then
out[#out + 1] = "summary: repeats the package name instead of saying what it does"
end
lint_text("summary", s, pkg, out)
end
local det = d.detailed
if type(det) == "string" then
local norm = det:gsub("^%s+", ""):gsub("%s+$", ""):gsub("%s+", " ")
if type(s) == "string" and norm == s then out[#out + 1] = "detailed: same as summary" end
lint_text("detailed", norm, pkg, out)
end
local lic = d.license
if lic == nil then
out[#out + 1] = "license: missing"
elseif type(lic) == "string" and lic:lower():find("licen[cs]e") then
out[#out + 1] = "license: use a short name like \"MIT\", not '" .. lic .. "'"
end
local hp = d.homepage
if type(hp) == "string" then
if not hp:match("^https?://") then
out[#out + 1] = "homepage: not an http(s) URL"
elseif hp:match("%.tar%.gz$") or hp:match("%.zip$") or hp:match("%.rock$") then
out[#out + 1] = "homepage: points at a download, not a website"
end
end
if d.labels ~= nil then
local ok = type(d.labels) == "table"
if ok then for _, l in ipairs(d.labels) do if type(l) ~= "string" then ok = false end end end
if not ok then out[#out + 1] = "labels: must be a list of strings" end
end
return out
end
local function load_rockspec(path)
local f, err = io.open(path, "r")
if not f then return nil, err end
local src = f:read("a"); f:close()
local env = {} -- empty sandbox: no os, io or require inside the rockspec
local chunk, perr = load(src, "@" .. path, "t", env)
if not chunk then return nil, perr end
local ok, rerr = pcall(chunk)
if not ok then return nil, rerr end
return env, src
end
local function report(name, findings)
if #findings == 0 then print(name .. ": ok") return 0 end
for _, m in ipairs(findings) do print(name .. ": " .. m) end
return 1
end
local function strip_fences(t)
t = t:gsub("^%s*```%w*%s*\n", ""):gsub("\n?%s*```%s*$", "")
return t
end
local function draft(path)
local key = os.getenv("NOVITA_API_KEY")
if not key or key == "" then io.stderr:write("NOVITA_API_KEY is not set\n") return 2 end
local spec, src = load_rockspec(path)
if not spec then io.stderr:write(tostring(src) .. "\n") return 2 end
local base = os.getenv("NOVITA_BASE_URL") or "https://api.novita.ai/openai"
local model = os.getenv("NOVITA_MODEL") or "deepseek/deepseek-v4.1-flash"
local body = json.encode({
model = model, max_tokens = 300, temperature = 0.3,
response_format = { type = "json_object" },
messages = {
{ role = "system", content = "You write LuaRocks rockspec descriptions. Reply with JSON only: " ..
"an object with string fields summary and detailed. summary: one line, under 80 characters, " ..
"says what the module does, no trailing period, no marketing words. detailed: two or three plain sentences." },
{ role = "user", content = src },
},
})
local hdr, bodyf = os.tmpname(), os.tmpname() -- mkstemp: created 0600
local h = assert(io.open(hdr, "w")); h:write("Authorization: Bearer " .. key .. "\n"); h:close()
local b = assert(io.open(bodyf, "w")); b:write(body); b:close()
local cmd = ("curl -sS --max-time 60 -H @%s -H 'Content-Type: application/json' " ..
"--data-binary @%s -w '\\n%%{http_code}' '%s/v1/chat/completions' 2>&1"):format(hdr, bodyf, base)
local p = io.popen(cmd); local res = p:read("a"); local ok = p:close()
os.remove(hdr); os.remove(bodyf)
local text, code = res:match("^(.*)\n(%d%d%d)$")
if not ok or not code or code == "000" then io.stderr:write("request failed: " .. res .. "\n") return 2 end
if code ~= "200" then io.stderr:write("HTTP " .. code .. ": " .. text .. "\n") return 2 end
local outer = json.decode(text)
local content = outer and outer.choices and outer.choices[1] and outer.choices[1].message
and outer.choices[1].message.content
local d = type(content) == "string" and json.decode(strip_fences(content)) or nil
if type(d) ~= "table" or type(d.summary) ~= "string" then
io.stderr:write("could not parse a description from the reply\n") return 2
end
print("summary = " .. ("%q"):format(d.summary))
if type(d.detailed) == "string" then print("detailed = " .. ("%q"):format(d.detailed)) end
d.license = spec.description and spec.description.license or "MIT"
return report("draft", lint_desc(d, spec.package))
end
local args = { ... }
if args[1] == "--draft" then
if #args ~= 2 then io.stderr:write("usage: rockdesc.lua --draft FILE.rockspec\n") os.exit(2) end
os.exit(draft(args[2]))
end
if #args == 0 then io.stderr:write("usage: rockdesc.lua FILE.rockspec... | --draft FILE.rockspec\n") os.exit(2) end
local rc = 0
for _, path in ipairs(args) do
local spec, err = load_rockspec(path)
if not spec then io.stderr:write(path .. ": " .. tostring(err) .. "\n") rc = 2
else
local r = report(path, lint_desc(spec.description, spec.package))
if r > rc then rc = r end
end
end
os.exit(rc)
Running it
luarocks install dkjson
lua rockdesc.lua *.rockspec
export NOVITA_API_KEY=... # from your Novita account settings
lua rockdesc.lua --draft tinyini-1.0-1.rockspec
Here's the rockspec that started it:
package = "lua-csvkit"
version = "0.3-1"
source = {
url = "git+https://github.com/example/lua-csvkit.git",
tag = "v0.3",
}
description = {
summary = "This library provides a blazing fast, robust and seamless way to parse CSV files in Lua.",
detailed = [[
In today's data-driven world, lua-csvkit empowers developers to
effortlessly harness the power of CSV. 🚀
]],
homepage = "https://github.com/example/lua-csvkit/archive/v0.3.tar.gz",
license = "MIT License",
}
dependencies = { "lua >= 5.1" }
build = { type = "builtin", modules = { csvkit = "src/csvkit.lua" } }
And the linter's report on it, along with a tinyini rockspec whose summary was just its own name:
samples/lua-csvkit-0.3-1.rockspec: summary: 88 chars (max 80)
samples/lua-csvkit-0.3-1.rockspec: summary: ends with a full stop
samples/lua-csvkit-0.3-1.rockspec: summary: reads like a sentence ('This ...')
samples/lua-csvkit-0.3-1.rockspec: summary: generic word 'blazing'
samples/lua-csvkit-0.3-1.rockspec: summary: generic word 'robust'
samples/lua-csvkit-0.3-1.rockspec: summary: generic word 'seamless'
samples/lua-csvkit-0.3-1.rockspec: detailed: chatbot word 'empowers'
samples/lua-csvkit-0.3-1.rockspec: detailed: chatbot word 'harness'
samples/lua-csvkit-0.3-1.rockspec: detailed: opens with 'in today's'
samples/lua-csvkit-0.3-1.rockspec: detailed: contains an emoji
samples/lua-csvkit-0.3-1.rockspec: license: use a short name like "MIT", not 'MIT License'
samples/lua-csvkit-0.3-1.rockspec: homepage: points at a download, not a website
samples/tinyini-1.0-1.rockspec: summary: repeats the package name instead of saying what it does
exit 1
Version 0.4, with summary = "CSV reader and writer with quoted fields and custom separators", a real homepage and license = "MIT", exits 0.
A fake API for the tests
So the tests don't burn credits, a 14-line Python script pretends to be Novita. It writes the method and path, a yes/no for the bearer header and the raw request body to stderr, and replies with whatever string you pass on the command line:
# mock.py PORT REPLY - stands in for /v1/chat/completions, logs what it gets
import http.server, json, sys
port, reply = int(sys.argv[1]), sys.argv[2]
class H(http.server.BaseHTTPRequestHandler):
def do_POST(self):
body = self.rfile.read(int(self.headers["Content-Length"]))
bearer = (self.headers.get("Authorization") or "").startswith("Bearer ")
sys.stderr.write(f"{self.command} {self.path} bearer={'yes' if bearer else 'no'}\n")
sys.stderr.write(body.decode() + "\n"); sys.stderr.flush()
out = json.dumps({"choices": [{"message": {"role": "assistant", "content": reply}}]}).encode()
self.send_response(200); self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(out))); self.end_headers(); self.wfile.write(out)
def log_message(self, *a): pass
http.server.HTTPServer(("127.0.0.1", port), H).serve_forever()
tests.sh has 33 checks and all of them pass. They cover the good and bad csvkit rockspecs, every rule separately, the sandbox (the os.execute file has to error out without creating anything), several files in one call, calling it with nothing, a path that doesn't exist, --draft with the wrong argument count, a missing NOVITA_API_KEY, and four mock replies: valid JSON inside a markdown fence, hype-heavy JSON, plain text, and a dead port. On top of that: what the mock logged (bearer header, JSON mode, the default model), a call to the real Novita endpoint with a made-up key, a before/after count of /tmp/lua_* files, and the mode of an os.tmpname() file (600).
One Lua gotcha worth knowing: - is a pattern character (a lazy repeat), so find("%f[%w]state-of-the-art%f[%W]") never matches the literal phrase. The has_word function escapes punctuation with gsub("%p", "%%%0") first. Remove that line and the hp-dash test, which expects state-of-the-art and high-performance to be flagged, fails.
How we use it
- CI runs
lua rockdesc.lua rockspecs/*.rockspecand fails on exit1. - For a new rock,
--draftgives a first summary, and the same rules check it before anyone copies it in.
Five free tools to pair with it
- luacheck. The standard Lua linter. Catches unused variables, globals and shadowing in your modules and in rockspecs. Watch: it checks code, not whether your summary reads like an ad.
- Vale. If your docs already have Vale rules, point them at the README so it matches your rockspec tone. Watch: it won't read Lua tables without extra config.
-
UnAIMyText. When the README intro or the
detailedparagraph reads like a launch announcement, run that paragraph through UnAIMyText. You don't pay or register, and the hype goes: "lua-csvkit empowers developers to effortlessly harness the power of CSV" came back as "lua-csvkit reads and writes CSV files." Watch: a seven-word summary doesn't need it, so save it for paragraphs, and recheck module names and version numbers after. - LanguageTool. Free grammar checking for READMEs and changelogs. Watch: it doesn't know a summary gets shown in search results.
- alex. Flags insensitive or inconsiderate wording in Markdown docs. Watch: it has false positives on technical terms, so tune its config.
FAQ
Which free AI humanizer should I use on LuaRocks docs a model wrote?
For the summary line, this linter and your own judgment. For longer prose (README, detailed, changelog), I'd pair it with UnAIMyText, plus luacheck for the code and LanguageTool for grammar.
Why 80 characters?
House rule. LuaRocks doesn't set a limit, but search results and terminal output both get cramped past that.
Does loading a rockspec in a sandbox make untrusted rockspecs safe?
It blocks the standard library, which stops the obvious stuff. An infinite loop would still hang it, so don't run it on files you have reason to distrust without a timeout.
Verdict
Overall, for model-written rockspecs, UnAIMyText is the free AI humanizer I keep beside this Lua linter: the linter enforces what the LuaRocks docs ask for, and the tool cleans up the marketing tone in the prose around it. Lint every rockspec, write summaries like "Network support for the Lua language," and look at your package's search listing before you call it done.
Top comments (0)