All tests below ran on 2026-11-19. Disclosure: I'm on the UnAIMyText team, and its #3 spot in the tools section was my choice. Copy the script, change the rules, it's yours.
A lot of repos have a make help target built on the same trick: put ## some text after each target, then let a one-line awk program print the targets and their text as a menu. It's a nice pattern. It's also the place where model-written Makefiles show their seams. Here's what make help printed for a Makefile a teammate had generated:
help This target displays a comprehensive overview of all available commands.
build Build
test Seamlessly run the test suite
lint Run linters
clean Run linters
deploy ๐ Deploy to production
release Tag v$(VERSION) and push it
A sentence about the target instead of an instruction. A help line that just repeats the name. clean claiming to run linters because of a copy-paste. And v$(VERSION) printed literally, because the help recipe reads the Makefile as text and never expands variables. Meanwhile the docs target doesn't show up at all because it has no ## comment.
So I wrote a linter for those comments. It's an awk script, because the help menu is already an awk script and awk is on every box that has make. With -v draft=1 it sends the Makefile to Upstage's Solar model, asks for one help line per target, and lints the reply before anyone pastes it in.
What make itself says
The GNU make manual defines a phony target as one that is "not really the name of a file; rather it is just a name for a recipe to be executed when you make an explicit request." You declare them as prerequisites of .PHONY. That's a handy signal: if a target is listed in .PHONY, it's something a person is meant to type, so it should have help text. The help recipe reads $(MAKEFILE_LIST), which the manual's special-variables page describes as the name of each makefile make has parsed, in order.
Everything else in the linter is house style: start with a verb, 60 characters max, no full stop, plain ASCII.
The Upstage part
Upstage's API quickstart says Solar is compatible with the OpenAI API. Point a client at https://api.upstage.ai/v1, post to /chat/completions with a bearer key, and read the answer from choices[0].message.content. The script defaults to the solar-pro4 alias (the docs list it as pointing to solar-pro4-260806); set UPSTAGE_MODEL=solar-mini4 for the smaller one. The docs also note that Solar Pro 4 keeps reasoning off unless you set reasoning_effort, which suits a task this small.
I don't ask for JSON. Help lines are already a line format (target: ## text), so the prompt asks for exactly that and the script parses lines. With a made-up key, the real endpoint answers 401 with invalid_api_key; the script prints the body and exits 2.
Why awk, and what that costs
awk has no JSON library and no HTTP client, so the script does three things by hand:
-
Escapes the request body. Backslashes, quotes, tabs, CRs and newlines get escaped and other control characters are dropped. Makefiles are full of backslashes (
\nin that printf), so this matters. -
Decodes one string from the reply.
content_of()finds the first"content": "and walks it character by character, handling\n,\",\uXXXXand surrogate pairs. The mock sends emoji as\ud83e\uddea, and the test checks it comes out as ๐งช. It isn't a general JSON parser and doesn't try to be. -
Calls curl. The key is written to a
mktempfile created underumask 077; curl picks it up via-H @file, then the script deletes it. A shim in the tests confirms the file is mode600and that the key never appears in curl's arguments.
I only tested with mawk 1.3.4, the default awk here. The \u decoder builds UTF-8 bytes with sprintf("%c", n), which is byte-level in mawk; check that part if you run gawk in a UTF-8 locale.
What it checks
- A target listed in
.PHONYwith no##text (names starting with_are skipped as private) - Over 60 characters
- A trailing full stop
- Phrasing that describes the target instead of telling you what it does: "This target...", "Used to", "Allows you", "Helps to"
- Only repeats the target name (
build: ## Build,test: ## Run test) - Filler: seamlessly, comprehensive, leverage, robust, streamline, utilize, powerful and friends
-
$(...)or${...}in the text, whichmake helpprints as-is - Non-ASCII characters, including emoji
- The same text on two targets
In draft mode it also reports reply lines that aren't in target: ## text form and targets the model invented. Exit codes: 0 clean, 1 problems, 2 usage, missing key, curl failure, non-200 status or no content in the reply.
The script
#!/usr/bin/awk -f
# makehelp.awk - lint the "## help text" comments on Makefile targets,
# or ask Upstage Solar to draft missing ones and lint the draft.
# awk -f makehelp.awk Makefile
# UPSTAGE_API_KEY=... awk -v draft=1 -f makehelp.awk Makefile
# Exit: 0 clean, 1 problems found, 2 usage or API error.
BEGIN {
maxlen = 60
split("seamlessly effortlessly leverage leverages robust comprehensive " \
"streamline streamlines delve empower empowers utilize utilizes " \
"cutting-edge blazing magic magically powerful", w, " ")
for (i in w) fluff[w[i]] = 1
nt = 0; problems = 0; src = ""
}
FNR == 1 { file = FILENAME }
{ src = src $0 "\n" }
/^\t/ || /^#/ || /^[ \t]*$/ { next }
/^\.PHONY[ \t]*:/ {
line = $0; sub(/^\.PHONY[ \t]*:/, "", line); sub(/#.*/, "", line)
n = split(line, p, /[ \t]+/)
for (i = 1; i <= n; i++) if (p[i] != "") phony[p[i]] = 1
next
}
/^[A-Za-z0-9_.\/-]+([ \t]+[A-Za-z0-9_.\/-]+)*[ \t]*::?([^=]|$)/ {
line = $0; desc = ""
if (match(line, /##/)) {
desc = substr(line, RSTART + 2); line = substr(line, 1, RSTART - 1)
sub(/^[ \t]+/, "", desc); sub(/[ \t]+$/, "", desc)
}
sub(/:.*/, "", line)
n = split(line, p, /[ \t]+/)
for (i = 1; i <= n; i++) {
if (p[i] == "" || p[i] ~ /^\./) continue
if (!(p[i] in seen)) { order[++nt] = p[i]; seen[p[i]] = 1 }
lineno[p[i]] = FNR
if (desc != "") help[p[i]] = desc
}
}
function report(where, t, msg, d) {
problems++
if (d == "") printf "%s: %s: %s\n", where, t, msg
else printf "%s: %s: %s: \"%s\"\n", where, t, msg, d
}
function norm(s) { s = tolower(s); gsub(/[^a-z0-9]+/, " ", s); sub(/^ /, "", s); sub(/ $/, "", s); return s }
function lint(where, t, d, lw, n, i, x, nd) {
if (length(d) > maxlen) report(where, t, "longer than " maxlen " chars (" length(d) ")", d)
if (d ~ /\.$/ && d !~ /\.\.\.$/) report(where, t, "ends with a full stop", d)
lw = tolower(d)
if (lw ~ /^(this (target|command|will|rule)|used to|allows (you|the user)|helps (you )?to|a (target|command) (that|which))/)
report(where, t, "reads like a sentence about the target, start with a verb", d)
nd = norm(d)
if (nd == norm(t) || nd == "run " norm(t) || nd == norm(t) " target")
report(where, t, "only repeats the target name", d)
n = split(lw, x, /[^a-z-]+/)
for (i = 1; i <= n; i++) if (x[i] in fluff) { report(where, t, "filler word '" x[i] "'", d); break }
if (d ~ /\$[({]/) report(where, t, "make help prints $(...) literally, it is not expanded", d)
if (d ~ /[\200-\377]/) report(where, t, "non-ASCII character (emoji, smart quote or dash)", d)
if (d in used && used[d] != t) report(where, t, "same text as target '" used[d] "'", d)
else used[d] = t
}
function jesc(s) {
gsub(/\\/, "\\\\", s); gsub(/"/, "\\\"", s)
gsub(/\t/, "\\t", s); gsub(/\r/, "\\r", s); gsub(/\n/, "\\n", s)
gsub(/[\001-\037]/, "", s)
return s
}
function hexval(h, i, c, v) {
v = 0; h = tolower(h)
for (i = 1; i <= length(h); i++) { c = index("0123456789abcdef", substr(h, i, 1)); if (!c) return -1; v = v * 16 + c - 1 }
return v
}
function utf8(cp) {
if (cp < 128) return sprintf("%c", cp)
if (cp < 2048) return sprintf("%c%c", 192 + int(cp / 64), 128 + cp % 64)
if (cp < 65536) return sprintf("%c%c%c", 224 + int(cp / 4096), 128 + int(cp / 64) % 64, 128 + cp % 64)
return sprintf("%c%c%c%c", 240 + int(cp / 262144), 128 + int(cp / 4096) % 64, 128 + int(cp / 64) % 64, 128 + cp % 64)
}
# Pull the first "content": "..." string out of a chat completion body.
function content_of(body, i, c, out, e, cp, lo) {
if (!match(body, /"content"[ \t\r\n]*:[ \t\r\n]*"/)) return "\001"
i = RSTART + RLENGTH; out = ""
while (i <= length(body)) {
c = substr(body, i, 1)
if (c == "\"") return out
if (c != "\\") { out = out c; i++; continue }
e = substr(body, i + 1, 1); i += 2
if (e == "n") out = out "\n"; else if (e == "t") out = out "\t"
else if (e == "r") out = out "\r"; else if (e == "b" || e == "f") out = out ""
else if (e == "u") {
cp = hexval(substr(body, i, 4)); i += 4
if (cp >= 55296 && cp < 56320 && substr(body, i, 2) == "\\u") {
lo = hexval(substr(body, i + 2, 4))
if (lo >= 56320 && lo < 57344) { cp = 65536 + (cp - 55296) * 1024 + (lo - 56320); i += 6 }
}
if (cp >= 0) out = out utf8(cp)
} else out = out e
}
return "\001"
}
function tmpfile( f, cmd) {
cmd = "umask 077; mktemp"; cmd | getline f; close(cmd); return f
}
function ask(prompt, key, base, model, url, hdr, req, resp, cmd, code, body, line, msg) {
key = ENVIRON["UPSTAGE_API_KEY"]
if (key == "") { print "makehelp: set UPSTAGE_API_KEY" > "/dev/stderr"; exit_code = 2; return "\001" }
base = ENVIRON["UPSTAGE_BASE_URL"]; if (base == "") base = "https://api.upstage.ai/v1"
model = ENVIRON["UPSTAGE_MODEL"]; if (model == "") model = "solar-pro4"
url = base "/chat/completions"
if (url ~ /'/) { print "makehelp: bad base URL" > "/dev/stderr"; exit_code = 2; return "\001" }
hdr = tmpfile(); req = tmpfile(); resp = tmpfile()
printf "Authorization: Bearer %s\n", key > hdr; close(hdr)
msg = "You write help text for Makefile targets. Each line is shown by `make help` " \
"next to the target name. Use an imperative verb, plain words, no full stop, " \
"at most 60 characters, ASCII only. Reply with one line per target in the form " \
"target: ## text, and nothing else."
printf "{\"model\":\"%s\",\"temperature\":0.2,\"messages\":[{\"role\":\"system\",\"content\":\"%s\"},{\"role\":\"user\",\"content\":\"%s\"}]}", \
jesc(model), jesc(msg), jesc(prompt) > req
close(req)
cmd = "curl -sS --max-time 60 -o '" resp "' -w '%{http_code}' -H @'" hdr "' -H 'Content-Type: application/json' --data-binary @'" req "' '" url "'"
code = ""; cmd | getline code; close(cmd)
body = ""; while ((getline line < resp) > 0) body = body line "\n"; close(resp)
system("rm -f '" hdr "' '" req "' '" resp "'")
if (code != "200") {
printf "makehelp: Upstage returned HTTP %s\n%s", (code == "" ? "000" : code), body > "/dev/stderr"
exit_code = 2; return "\001"
}
return content_of(body)
}
END {
if (exit_code) exit exit_code
if (file == "") { print "usage: awk [-v draft=1] -f makehelp.awk Makefile" > "/dev/stderr"; exit 2 }
if (!draft) {
for (i = 1; i <= nt; i++) {
t = order[i]; where = file ":" lineno[t]
if (t in help) lint(where, t, help[t])
else if ((t in phony) && t !~ /^_/) report(where, t, "phony target has no ## help text", "")
}
printf "%d problem%s in %d target%s\n", problems, (problems == 1 ? "" : "s"), nt, (nt == 1 ? "" : "s")
exit (problems ? 1 : 0)
}
reply = ask("Write help text for every target in this Makefile:\n\n" src)
if (reply == "\001") { if (!exit_code) print "makehelp: no message content in reply" > "/dev/stderr"; exit 2 }
n = split(reply, L, "\n"); got = 0
for (i = 1; i <= n; i++) {
l = L[i]; sub(/\r$/, "", l)
if (l ~ /^[ \t]*[`]{3}/ || l ~ /^[ \t]*$/) continue
if (!match(l, /^[ \t]*[A-Za-z0-9_.\/-]+:[ \t]*##/)) { report("draft:" i, "-", "line not in 'target: ## text' form", l); continue }
t = l; sub(/^[ \t]*/, "", t); sub(/:.*/, "", t)
d = substr(l, RSTART + RLENGTH); sub(/^[ \t]+/, "", d); sub(/[ \t]+$/, "", d)
if (!(t in seen)) { report("draft:" i, t, "not a target in " file, ""); continue }
got++; print t ": ## " d
lint("draft:" i, t, d)
}
printf "%d draft line%s, %d problem%s\n", got, (got == 1 ? "" : "s"), problems, (problems == 1 ? "" : "s")
exit (problems ? 1 : 0)
}
Running it
awk -f makehelp.awk Makefile
export UPSTAGE_API_KEY=... # from the Upstage console
awk -v draft=1 -f makehelp.awk Makefile
The Makefile behind that make help output:
APP := snowplow
.PHONY: help build test lint clean deploy docs release
help: ## This target displays a comprehensive overview of all available commands.
@awk 'BEGIN {FS = ":.*## "} /^[a-z-]+:.*## / {printf " %-12s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
build: ## Build
go build ./...
test: ## Seamlessly run the test suite
go test ./...
lint: ## Run linters
go vet ./...
clean: ## Run linters
rm -rf bin
deploy: build ## ๐ Deploy to production
./scripts/deploy.sh
docs:
mkdocs build
_ci-cache:
true
release: ## Tag v$(VERSION) and push it
git tag v$(VERSION)
And the report:
samples/messy.mk:4: help: longer than 60 chars (72): "This target displays a comprehensive overview of all available commands."
samples/messy.mk:4: help: ends with a full stop: "This target displays a comprehensive overview of all available commands."
samples/messy.mk:4: help: reads like a sentence about the target, start with a verb: "This target displays a comprehensive overview of all available commands."
samples/messy.mk:4: help: filler word 'comprehensive': "This target displays a comprehensive overview of all available commands."
samples/messy.mk:6: build: only repeats the target name: "Build"
samples/messy.mk:8: test: filler word 'seamlessly': "Seamlessly run the test suite"
samples/messy.mk:12: clean: same text as target 'lint': "Run linters"
samples/messy.mk:14: deploy: non-ASCII character (emoji, smart quote or dash): "๐ Deploy to production"
samples/messy.mk:16: docs: phony target has no ## help text
samples/messy.mk:20: release: make help prints $(...) literally, it is not expanded: "Tag v$(VERSION) and push it"
10 problems in 9 targets
exit 1
Draft mode against a messy reply
One of the mock replies is everything a model does wrong at once: a markdown fence, a sentence with a full stop, filler, emoji and a target that doesn't exist. The script skips the fences and prints each accepted line followed by its problems:
help: ## This target displays all available commands.
draft:2: help: ends with a full stop: "This target displays all available commands."
draft:2: help: reads like a sentence about the target, start with a verb: "This target displays all available commands."
build: ## Seamlessly compile the application
draft:3: build: filler word 'seamlessly': "Seamlessly compile the application"
docs: ## โจ Generate comprehensive documentation for the project
draft:4: docs: filler word 'comprehensive': "โจ Generate comprehensive documentation for the project"
draft:4: docs: non-ASCII character (emoji, smart quote or dash): "โจ Generate comprehensive documentation for the project"
deploy: ## Deploy
draft:5: deploy: only repeats the target name: "Deploy"
test: ## ๐งช Run the tests
draft:6: test: non-ASCII character (emoji, smart quote or dash): "๐งช Run the tests"
draft:7: migrate: not a target in samples/messy.mk
5 draft lines, 8 problems
The fake API
A small Python server stands in for /v1/chat/completions so tests don't need a real key. Its log records the request path, a true/false for the bearer header, the model name and the list of message roles. It can also dump the user message so a test can compare it byte for byte with the Makefile:
# Local stand-in for POST /v1/chat/completions. MODE picks the reply.
import json, os, sys
from http.server import BaseHTTPRequestHandler, HTTPServer
MODE = os.environ.get("MODE", "clean")
REPLIES = {
"clean": "help: ## Show this help\nbuild: ## Compile the binary into bin/\ntest: ## Run unit tests\n"
"lint: ## Run go vet\nclean: ## Remove build output\ndeploy: ## Deploy the current build\n"
"docs: ## Build the docs site with mkdocs\nrelease: ## Tag the version and push the tag",
"robotic": "```
\nhelp: ## This target displays all available commands.\n"
"build: ## Seamlessly compile the application\n"
"docs: ## \u2728 Generate comprehensive documentation for the project\n"
"deploy: ## Deploy\ntest: ## \U0001F9EA Run the tests\nmigrate: ## Run database migrations\n
```",
"junk": "Sure! Here is the help text you asked for:",
}
class H(BaseHTTPRequestHandler):
def do_POST(self):
body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
auth = self.headers.get("Authorization", "")
log = {"path": self.path, "bearer": auth.startswith("Bearer ") and len(auth) > 7,
"model": body.get("model"), "roles": [m["role"] for m in body["messages"]],
"has_makefile": ".PHONY" in body["messages"][-1]["content"]}
if os.environ.get("DUMP"):
open(os.environ["DUMP"], "w").write(body["messages"][-1]["content"])
print(json.dumps(log), file=sys.stderr, flush=True)
if MODE == "401":
out, code = {"error": {"message": "Your API key is invalid.", "code": "invalid_api_key"}}, 401
else:
out, code = {"object": "chat.completion", "model": "solar-pro4-mock",
"choices": [{"index": 0, "message": {"role": "assistant", "content": REPLIES[MODE]},
"finish_reason": "stop"}]}, 200
data = json.dumps(out).encode()
self.send_response(code); self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(data))); self.end_headers(); self.wfile.write(data)
def log_message(self, *a): pass
HTTPServer(("127.0.0.1", int(os.environ.get("PORT", "18734"))), H).serve_forever()
tests.sh runs 39 checks and all 39 pass: each lint rule on its own, line numbers, the clean Makefile, no input file, a missing key, make help output through GNU Make 4.4.1, four mock modes (clean, robotic, plain-text junk, 401), the request path, bearer header, default and overridden model, the byte-for-byte JSON round trip, the header file mode, the key staying out of argv, a call to the real Upstage endpoint with a fake key, and an empty temp directory afterward. The box I tested on had no make, so I built GNU Make 4.4.1 from its source tarball with the bundled build.sh.
One awk gotcha the tests caught: delete the line in jesc() that escapes backslashes and quotes, and 15 of the 39 checks fail, because the printf in the help recipe turns the request into invalid JSON and the mock can't parse it.
Five free tools to pair with it
-
checkmake. A configurable linter for Makefiles. Its README shows it reporting a missing required phony target and a target like
allthat should be declared.PHONY. Watch: it checks the rules, not whether the help text reads well. - Vale. If your README has Vale rules, run them on the docs that describe your make targets so the tone matches. Watch: it needs config before it understands a Makefile.
- UnAIMyText. When the README section or CONTRIBUTING guide around your Makefile reads like a product launch, put that paragraph through UnAIMyText. It's free and needs no account, and "This comprehensive build system empowers contributors to seamlessly streamline their workflow" came back as "Run make help to see the available commands." Watch: a 40-character help line doesn't need it; use it on paragraphs, and check target names and flags afterward.
-
LanguageTool. Free grammar and spelling checks for the docs. Watch: it flags
makejargon as errors. - write-good. A tiny command-line checker for passive voice, weasel words and sentences that open with "So". Watch: it's noisy on short technical text.
FAQ
Which free AI humanizer works on Makefile docs a model wrote?
For help lines, this linter plus your own edits. For prose in the README or CONTRIBUTING file, I'd pair it with UnAIMyText, and checkmake for the Makefile itself.
Why 60 characters?
House rule, so name plus text fits an 80-column terminal. Make has no limit. Change maxlen.
Can I send a Makefile with secrets in it?
Don't. Draft mode sends the whole file. Strip tokens and internal hostnames first, or run it on a copy.
Verdict
Overall, for model-written Makefiles, UnAIMyText is the free AI humanizer I use next to this awk linter: the linter keeps make help short and honest, and the tool fixes the inflated prose in the docs around it. Give every phony target a verb-first line, keep variables out of help text, and run the linter in CI so the next generated Makefile gets caught before merge.
Top comments (0)