makeover.lua

#!/usr/bin/env lua
-- Copyright (c) 2026 David Balishyan
-- SPDX-License-Identifier: MIT
-- Makeover: a small build system designed to be vendored with a project.

local BS_FILE_NAME = "Buildfile"
local BS_NORM_FORM = "buildfile"

local variables = {}
local variable_lines = {}
local overrides = {}
local variable_cache = {}
local targets = {}
local target_order = {}
local first_target = nil
local source_name = BS_FILE_NAME
local verbose_flag = false
local dry_run_flag = false
local build_dir = "."

local function lstrip(s)
    return (s:gsub("^%s+", ""))
end

local function rstrip(s)
    return (s:gsub("%s+$", ""))
end

local function trim(s)
    return (s:gsub("^%s+", ""):gsub("%s+$", ""))
end

local function die_error(message, line, source)
    local prefix = ""
    if line ~= nil then
        prefix = (source or source_name) .. ":" .. line .. ": "
    end
    io.stderr:write("makeover: error: " .. prefix .. message .. "\n")
    os.exit(1)
end

local function shell_quote(value)
    return "'" .. value:gsub("'", "'\\''") .. "'"
end

local function cwd()
    local f = io.popen("pwd")
    if not f then return nil end
    local line = f:read("*l")
    f:close()
    return line
end

local function realpath(path)
    local f = io.popen("realpath -- " .. shell_quote(path) .. " 2>/dev/null")
    if not f then return nil end
    local line = f:read("*l")
    f:close()
    return line
end

local function dirname(path)
    local d = path:match("^(.*)/[^/]*$")
    if d then return d end
    if path == "" then return "" end
    return "."
end

local function basename(path)
    return path:match("([^/]*)/?$")
end

local function prefix_path(path)
    if path:sub(1, 1) == "/" then return path end
    return build_dir .. "/" .. path
end

local function isfile(path)
    local f = io.popen("test -f " .. shell_quote(path) .. " 2>/dev/null && printf ok")
    if not f then return false end
    local line = f:read("*l")
    f:close()
    return (line == "ok")
end

local function stat_mtime(path)
    local f = io.popen("stat -c %Y -- " .. shell_quote(prefix_path(path)) .. " 2>/dev/null")
    if not f then return nil end
    local line = f:read("*l")
    f:close()
    if not line then return nil end
    return tonumber(line)
end

local function path_exists(path)
    return stat_mtime(path) ~= nil
end

local function is_buildfile_name(name)
    return (name:gsub("[^A-Za-z0-9]", "")):lower() == BS_NORM_FORM
end

local function matching_buildfile(directory)
    local f = io.popen("/bin/ls -Ap -- " .. shell_quote(directory) .. " 2>/dev/null")
    if not f then return nil end
    local matches = {}
    for line in f:lines() do
        local is_dir = line:sub(-1) == "/"
        local entry = is_dir and line:sub(1, -2) or line
        if not is_dir and is_buildfile_name(entry) then
            matches[#matches + 1] = directory .. "/" .. entry
        end
    end
    f:close()
    if #matches > 1 then
        local names = {}
        for _, m in ipairs(matches) do names[#names + 1] = basename(m) end
        table.sort(names)
        die_error("multiple Buildfiles found in '" .. directory .. "': " ..
            table.concat(names, ", "))
    end
    return matches[1]
end

local function ancestor_directories(start)
    local dir = realpath(start)
    local result = {}
    while true do
        result[#result + 1] = dir
        local parent = dirname(dir)
        if parent == dir then break end
        dir = parent
    end
    return result
end

local function discover_buildfile(current, script_path)
    local current_directory = cwd() or current
    local script_dir = dirname(realpath(script_path))
    local origins = { current_directory, script_dir }
    local searched = {}
    for _, origin in ipairs(origins) do
        for _, directory in ipairs(ancestor_directories(origin)) do
            if not searched[directory] then
                searched[directory] = true
                local match = matching_buildfile(directory)
                if match then return match end
            end
        end
    end
    die_error("no Buildfile found in the current directory, its parents, or the Makeover script's parents")
end

local function has_magic(path)
    return path:find("%*") ~= nil
        or path:find("?", 1) ~= nil
        or path:find("%[", 1) ~= nil
end

local function fnmatch(name, pat)
    local out = {}
    local i = 1
    local n = #pat
    while i <= n do
        local c = pat:sub(i, i)
        if c == "*" then
            out[#out + 1] = ".*"
        elseif c == "?" then
            out[#out + 1] = "."
        elseif c == "[" then
            local j = pat:find("]", i + 1)
            if j then
                out[#out + 1] = pat:sub(i, j)
                i = j
            else
                out[#out + 1] = "%["
            end
        elseif c:find("[%^%$%(%)%%%.%+%-%*%?%[%]]") then
            out[#out + 1] = "%" .. c
        else
            out[#out + 1] = c
        end
        i = i + 1
    end
    return string.match(name, "^" .. table.concat(out) .. "$") ~= nil
end

local function listdir(path)
    local entries = {}
    local f = io.popen("/bin/ls -Ap -- " .. shell_quote(prefix_path(path)) .. " 2>/dev/null")
    if f then
        for line in f:lines() do
            local is_dir = line:sub(-1) == "/"
            local name = is_dir and line:sub(1, -2) or line
            entries[#entries + 1] = { name = name, dir = is_dir }
        end
        f:close()
    end
    return entries
end

local glob
glob = function(pattern)
    local results = {}
    local dirpart, basepart = pattern:match("^(.*)/([^/]*)$")
    if not dirpart then
        dirpart, basepart = "", pattern
    end
    if not has_magic(dirpart) then
        if not has_magic(basepart) then
            if path_exists(pattern) then
                results[#results + 1] = pattern
            end
        else
            local base = dirpart ~= "" and dirpart or "."
            for _, e in ipairs(listdir(base)) do
                if fnmatch(e.name, basepart) then
                    results[#results + 1] = dirpart ~= "" and (dirpart .. "/" .. e.name) or e.name
                end
            end
        end
    else
        for _, d in ipairs(glob(dirpart)) do
            for _, e in ipairs(listdir(d)) do
                if e.dir and fnmatch(e.name, basepart) then
                    results[#results + 1] = d .. "/" .. e.name
                end
            end
        end
    end
    return results
end

local function matching_paren(text, start)
    local depth = 0
    for i = start, #text do
        local ch = text:sub(i, i)
        if ch == "(" then
            depth = depth + 1
        elseif ch == ")" then
            depth = depth - 1
            if depth == 0 then return i end
        end
    end
    return -1
end

local function append(t, x)
    local out = {}
    for i = 1, #t do out[i] = t[i] end
    out[#out + 1] = x
    return out
end

local resolve_variable
local expand
expand = function(text, line, automatic, stack)
    stack = stack or {}
    local result = {}
    local i = 1
    local n = #text
    while i <= n do
        local c = text:sub(i, i)
        if c ~= "$" then
            result[#result + 1] = c
            i = i + 1
        elseif i + 1 > n then
            result[#result + 1] = "$"
            i = i + 1
        else
            local marker = text:sub(i + 1, i + 1)
            if marker == "$" then
                result[#result + 1] = "$"
                i = i + 2
            elseif automatic and automatic[marker] then
                result[#result + 1] = automatic[marker]
                i = i + 2
            elseif marker ~= "(" then
                result[#result + 1] = "$"
                i = i + 1
            else
                local closing = matching_paren(text, i + 1)
                if closing == -1 then
                    die_error("unterminated variable reference", line)
                end
                local body = text:sub(i + 2, closing - 1)
                if body == "wildcard" or body:sub(1, 9) == "wildcard " then
                    local pats = expand(trim(body:sub(9)), line, automatic, stack)
                    local matches = {}
                    local seen = {}
                    for pat in pats:gmatch("%S+") do
                        for _, m in ipairs(glob(pat)) do
                            if not seen[m] then
                                seen[m] = true
                                matches[#matches + 1] = m
                            end
                        end
                    end
                    result[#result + 1] = table.concat(matches, " ")
                    i = closing + 1
                elseif not body:match("^[A-Za-z_][A-Za-z0-9_]*$") then
                    die_error("invalid variable reference '$(" .. body .. ")'", line)
                else
                    result[#result + 1] = resolve_variable(body, line, automatic, stack)
                    i = closing + 1
                end
            end
        end
    end
    return table.concat(result)
end

resolve_variable = function(name, line, automatic, stack)
    if automatic == nil and variable_cache[name] ~= nil then
        return variable_cache[name]
    end
    for idx = 1, #stack do
        if stack[idx] == name then
            local cycle = table.concat(stack, " -> ", idx, #stack) .. " -> " .. name
            die_error("variable cycle detected: " .. cycle, line)
        end
    end
    local value
    if overrides[name] ~= nil then
        value = expand(overrides[name], line, automatic, append(stack, name))
    elseif variables[name] ~= nil then
        value = expand(variables[name], variable_lines[name] or line, automatic, append(stack, name))
    elseif os.getenv(name) ~= nil then
        value = expand(os.getenv(name), line, automatic, append(stack, name))
    else
        die_error("undefined variable '" .. name .. "'", line)
    end
    if automatic == nil then variable_cache[name] = value end
    return value
end

local function parse_assignment(line)
    local name, rest = line:match("^([A-Za-z_][A-Za-z0-9_]*)%s*(.*)$")
    if not name then return nil end
    local op, value = rest:match("^(%?=)%s*(.*)$")
    if op then return name, op, value end
    op, value = rest:match("^(:=)%s*(.*)$")
    if op then return name, op, value end
    op, value = rest:match("^(=)%s*(.*)$")
    if op then return name, op, value end
    return nil
end

local function trailing_backslashes(value)
    local count = 0
    local i = #value
    while i >= 1 and value:sub(i, i) == "\\" do
        count = count + 1
        i = i - 1
    end
    return count
end

local function validate_word(value, kind, line)
    if value == "" then
        die_error(kind .. " name cannot be empty", line)
    end
    if value:find("%s") then
        die_error(kind .. " name cannot contain whitespace: '" .. value .. "'", line)
    end
    if value:find("[=:]") then
        die_error("invalid " .. kind .. " name '" .. value .. "'", line)
    end
end

local function finish_parsing(raw_targets, raw_phony)
    for _, rt in ipairs(raw_targets) do
        local name = expand(rt.name, rt.line)
        validate_word(name, "target", rt.line)
        local expanded_prereqs = expand(rt.prereqs, rt.line)
        local prereqs = {}
        for p in expanded_prereqs:gmatch("%S+") do prereqs[#prereqs + 1] = p end
        for _, p in ipairs(prereqs) do
            validate_word(p, "prerequisite", rt.line)
        end
        if targets[name] ~= nil then
            die_error("duplicate target '" .. name .. "'", rt.line)
        end
        targets[name] = {
            name = name,
            prereqs = prereqs,
            recipes = rt.recipes,
            doc = rt.doc,
            group = rt.group,
            line = rt.line,
            phony = false,
        }
        target_order[#target_order + 1] = name
        if first_target == nil then first_target = name end
    end
    for _, phony in ipairs(raw_phony) do
        local expanded_names = expand(phony.names, phony.line)
        for n in expanded_names:gmatch("%S+") do
            validate_word(n, "phony target", phony.line)
            if targets[n] == nil then
                die_error(".PHONY refers to undeclared target '" .. n .. "'", phony.line)
            end
            targets[n].phony = true
        end
    end
end

local function parse_buildfile(path)
    local file, err = io.open(prefix_path(path), "r")
    if not file then die_error("cannot read Buildfile: " .. (err or "")) end

    local current_target = nil
    local current_group = "General"
    local pending_doc = {}
    local pending_recipe_lines = nil
    local pending_recipe_line = nil
    local raw_targets = {}
    local raw_phony = {}
    local line_number = 0

    for raw_line in file:lines() do
        line_number = line_number + 1
        local line = raw_line:gsub("\r?\n$", "")  -- rstrip \r\n
        local stripped = trim(line)

        if stripped == "" then
            pending_doc = {}
        elseif line:sub(1, 1):find("%s") then
            if current_target == nil then
                die_error("recipe found outside a target", line_number)
            end
            local content = lstrip(line)
            local continues = trailing_backslashes(content) % 2 == 1
            if continues then content = content:sub(1, -2) end
            if pending_recipe_lines == nil then
                pending_recipe_lines = { content }
                pending_recipe_line = line_number
            else
                pending_recipe_lines[#pending_recipe_lines + 1] = content
            end
            if not continues then
                current_target.recipes[#current_target.recipes + 1] = {
                    cmd = table.concat(pending_recipe_lines, " "),
                    line = pending_recipe_line,
                }
                pending_recipe_lines = nil
                pending_recipe_line = nil
            end
        else
            if pending_recipe_lines ~= nil then
                current_target.recipes[#current_target.recipes + 1] = {
                    cmd = table.concat(pending_recipe_lines, " "),
                    line = pending_recipe_line,
                }
                pending_recipe_lines = nil
                pending_recipe_line = nil
            end
            current_target = nil

            if stripped:sub(1, 1) == "#" then
                pending_doc[#pending_doc + 1] = trim(stripped:sub(2))
            elseif stripped:sub(1, 7) == "[group:" and stripped:sub(-1) == "]" then
                local group_name = trim(stripped:sub(9, -2))
                if group_name == "" then
                    die_error("group name cannot be empty", line_number)
                end
                current_group = group_name
                pending_doc = {}
            elseif stripped:sub(1, 1) == "[" then
                die_error("invalid group declaration", line_number)
            else
                local name, op, value = parse_assignment(line)
                if name then
                    variable_cache[name] = nil
                    if op == ":=" then
                        value = expand(value, line_number)
                    end
                    if not (op == "?=" and (variables[name] ~= nil
                        or os.getenv(name) ~= nil
                        or overrides[name] ~= nil)) then
                        variables[name] = value
                        variable_lines[name] = line_number
                    end
                    pending_doc = {}
                elseif stripped:sub(1, 6) == ".PHONY" then
                    if stripped:sub(1, 7) ~= ".PHONY:" then
                        die_error("expected '.PHONY: target ...'", line_number)
                    end
                    local colons = 0
                    for _ in stripped:gmatch(":") do colons = colons + 1 end
                    if colons ~= 1 then
                        die_error("invalid .PHONY declaration", line_number)
                    end
                    local _, _, names = stripped:find(":(.*)", 1)
                    local names_str = trim(names or "")
                    if names_str == "" then
                        die_error(".PHONY requires at least one target", line_number)
                    end
                    raw_phony[#raw_phony + 1] = { names = names_str, line = line_number }
                    pending_doc = {}
                else
                    local colons = 0
                    for _ in line:gmatch(":") do colons = colons + 1 end
                    if colons ~= 1 then
                        die_error("expected a target declaration", line_number)
                    end
                    local idx = line:find(":")
                    local raw_name = trim(line:sub(1, idx - 1))
                    local raw_prereqs = trim(line:sub(idx + 1))
                    if raw_name == "" then
                        die_error("target name cannot be empty", line_number)
                    end
                    local raw_target = {
                        name = raw_name,
                        prereqs = raw_prereqs,
                        recipes = {},
                        doc = table.concat(pending_doc, " "),
                        group = current_group,
                        line = line_number,
                    }
                    raw_targets[#raw_targets + 1] = raw_target
                    current_target = raw_target
                    pending_doc = {}
                end
            end
        end
    end
    file:close()
    finish_parsing(raw_targets, raw_phony)
end

local function list_targets()
    local groups = {}
    local grouped_targets = {}
    for _, name in ipairs(target_order) do
        local target = targets[name]
        if not grouped_targets[target.group] then
            groups[#groups + 1] = target.group
            grouped_targets[target.group] = {}
        end
        grouped_targets[target.group][#grouped_targets[target.group] + 1] = target
    end
    io.write("Available targets:\n")
    for _, group in ipairs(groups) do
        io.write("\n" .. group .. ":\n")
        local width = 0
        for _, target in ipairs(grouped_targets[group]) do
            if #target.name > width then width = #target.name end
        end
        for _, target in ipairs(grouped_targets[group]) do
            local suffix = ""
            if target.doc ~= "" then suffix = "  # " .. target.doc end
            io.write(string.format("  %-" .. width .. "s%s\n", target.name, suffix))
        end
    end
end

local function changed_prerequisites(target)
    local target_mtime = stat_mtime(target.name)
    if target_mtime == nil then
        local all = {}
        for _, p in ipairs(target.prereqs) do all[#all + 1] = p end
        return all
    end
    local changed = {}
    for _, prereq_name in ipairs(target.prereqs) do
        local prereq = targets[prereq_name]
        if prereq and prereq.phony then
            changed[#changed + 1] = prereq_name
        elseif not path_exists(prereq_name) then
            changed[#changed + 1] = prereq_name
        else
            local prereq_mtime = stat_mtime(prereq_name)
            if prereq_mtime and prereq_mtime > target_mtime then
                changed[#changed + 1] = prereq_name
            end
        end
    end
    return changed
end

local function needs_rebuild(target)
    local target_mtime = stat_mtime(target.name)
    if target.phony or target_mtime == nil then return true end
    for _, prereq_name in ipairs(target.prereqs) do
        local prereq = targets[prereq_name]
        if prereq and prereq.phony then return true end
        local prereq_mtime = stat_mtime(prereq_name)
        if prereq_mtime == nil then return true end
        if prereq_mtime > target_mtime then return true end
    end
    return false
end

local function recipe_options(command)
    local silent = false
    local ignore = false
    local i = 1
    while i <= #command and command:sub(i, i):find("[@%-]") do
        if command:sub(i, i) == "@" then
            silent = true
        else
            ignore = true
        end
        i = i + 1
    end
    return lstrip(command:sub(i)), silent, ignore
end

local function run_shell(command)
    local a, b, c = os.execute("/bin/sh -c " .. shell_quote(command))
    if type(a) == "number" then
        if a == 0 then return 0 end
        return math.floor(a / 256)
    end
    if b == "signal" then return 128 + (c or 0) end
    return c or 0
end

local function verbose_log(message)
    if not verbose_flag then return end
    io.write("[Makeover] " .. message .. "\n")
end

local function run_recipes(target)
    verbose_log("Building target: " .. target.name)
    local automatic = {
        ["@"] = target.name,
        ["<"] = target.prereqs[1] or "",
        ["^"] = table.concat(target.prereqs, " "),
        ["?"] = table.concat(changed_prerequisites(target), " "),
    }
    for _, recipe in ipairs(target.recipes) do
        local command, silent, ignore = recipe_options(recipe.cmd)
        command = expand(command, recipe.line, automatic, {})
        if command ~= "" then
            if not silent then
                io.write(command .. "\n")
                io.flush()
            end
            if not dry_run_flag then
                local return_code = run_shell("cd " .. shell_quote(build_dir) .. " && " .. command)
                if return_code ~= 0 and ignore then
                    io.stderr:write("makeover: warning: command failed with status " ..
                        return_code .. " (ignored): " .. command .. "\n")
                elseif return_code ~= 0 then
                    die_error("command failed with status " .. return_code .. ": " ..
                        command, recipe.line)
                end
            end
        end
    end
end

local completed = {}

local function build_target(name)
    if completed[name] then return end
    if targets[name] == nil then
        completed[name] = true
        return
    end
    local target = targets[name]
    for _, prereq in ipairs(target.prereqs) do build_target(prereq) end
    if needs_rebuild(target) then
        run_recipes(target)
    else
        verbose_log("Target '" .. target.name .. "' is up to date.")
    end
    completed[name] = true
end

local function validate_graph(name, path, validated)
    for idx = 1, #path do
        if path[idx] == name then
            local cycle = table.concat(path, " -> ", idx, #path) .. " -> " .. name
            local line = targets[name] and targets[name].line or nil
            die_error("dependency cycle detected: " .. cycle, line)
        end
    end
    if validated[name] then return end
    if targets[name] == nil then
        if not path_exists(name) then
            die_error("no rule to make target '" .. name .. "' and file not found")
        end
        validated[name] = true
        return
    end
    local target = targets[name]
    for _, prereq in ipairs(target.prereqs) do
        validate_graph(prereq, append(path, name), validated)
    end
    validated[name] = true
end

local USAGE = [[usage: makeover [options] [VAR=value ...] [target ...]

Build targets from the nearest Buildfile. The first target is used by default.

options:
  -f, --file PATH  use PATH as the Buildfile
  -h, --help       show this help message
  -l, --list       list documented targets without building
  -n, --dry-run    print recipe commands without running them
  -v, --verbose    show Makeover build status messages

variables:
  VAR=value  define or override a variable for this invocation
]]

local function parse_arguments(argument_list)
    local result = {
        help = false,
        list = false,
        dry = false,
        verbose = false,
        file = nil,
        overrides = {},
        targets = {},
    }
    local index = 1
    while index <= #argument_list do
        local argument = argument_list[index]
        if argument == "-h" or argument == "--help" then
            result.help = true
        elseif argument == "-l" or argument == "--list" then
            result.list = true
        elseif argument == "-v" or argument == "--verbose" then
            result.verbose = true
        elseif argument == "-n" or argument == "--dry-run" then
            result.dry = true
        elseif argument == "-f" or argument == "--file" then
            if result.file ~= nil then
                die_error("a Buildfile path may only be provided once")
            end
            index = index + 1
            if index > #argument_list then
                die_error(argument .. " requires a path")
            end
            result.file = argument_list[index]
        else
            local matched = argument:match("^%-%-file=(.*)$")
            if matched then
                if result.file ~= nil then
                    die_error("a Buildfile path may only be provided once")
                end
                result.file = matched
                if result.file == "" then
                    die_error("--file requires a path")
                end
            elseif argument:find("^-") then
                die_error("unknown option '" .. argument .. "'")
            else
                local name, op, value = parse_assignment(argument)
                if name and op == "=" then
                    result.overrides[name] = value
                else
                    result.targets[#result.targets + 1] = argument
                end
            end
        end
        index = index + 1
    end
    if result.list and #result.targets > 0 then
        die_error("--list does not accept targets")
    end
    return result
end

local function main()
    local result = parse_arguments(arg)
    if result.help then
        io.write(rstrip(USAGE) .. "\n")
        return 0
    end

    local selected_path
    if result.file == nil then
        selected_path = discover_buildfile(nil, arg[0] or "")
    else
        selected_path = realpath(result.file)
        if not selected_path or not isfile(selected_path) then
            die_error("Buildfile '" .. result.file .. "' not found")
        end
    end

    build_dir = dirname(selected_path)
    source_name = basename(selected_path)
    parse_buildfile(source_name)
    verbose_flag = result.verbose
    dry_run_flag = result.dry
    for k, v in pairs(result.overrides) do overrides[k] = v end

    if result.list then
        list_targets()
        return 0
    end

    local target_list = result.targets
    if #target_list == 0 then
        if first_target == nil then
            die_error("Buildfile contains no targets")
        end
        target_list = { first_target }
    end
    for _, name in ipairs(target_list) do
        validate_graph(name, {}, {})
    end
    for _, name in ipairs(target_list) do
        build_target(name)
    end
    return 0
end

os.exit(main())