Merge pull request #140 from lde-org/profiler

Add a profiler with flamegraph generation

Author: bycruz

CLAUDE.md

@@ -20,6 +20,7 @@ tests/          # Top-level integration test fixtures (e.g. some-package/)
 ```
 
 Each package has:
+
 - `src/` — source files (or `src/init.lua` as the entry point)
 - `lde.json` — package manifest
 - `lde.lock` — lockfile (auto-generated, commit this)
@@ -64,6 +65,7 @@ Each package has:
 `lde install` / `lde run` populate `target/` with symlinks (or copies for packages with a build script). Each dep is installed at `target/<alias>`.
 
 `package.path` is set to:
+
 ```
 target/?.lua
 target/?/init.lua
@@ -73,6 +75,7 @@ target/?.so  (or .dll / .dylib)
 So `require("json")` → `target/json/init.lua` → symlink to `packages/json/src/init.lua`.
 
 During `lde test`, `tests/` is also exposed as `target/tests`, so test files can do:
+
 ```lua
 local helper = require("tests.lib.something")  -- resolves to tests/lib/something.lua
 ```
@@ -88,6 +91,7 @@ local helper = require("tests.lib.something")  -- resolves to tests/lib/somethin
 ## Package API (`lde-core`)
 
 `require("lde-core")` returns a table with:
+
 - `lde.Package` — the Package class
 - `lde.Lockfile` — the Lockfile class
 - `lde.global` — global state/cache helpers
@@ -325,6 +329,19 @@ This outputs `packages/lde/lde` (or `lde.exe` on Windows). To install it globall
 
 **Important:** Tests in `packages/lde/tests/` run the actual `lde` CLI binary via `env.execPath()`. If those tests fail after source changes, recompile and replace the binary first.
 
+## Profiling `lde` code
+
+You can profile an lde package with `lde run --profile` with `--flamegraph` to additionally generate a flamegraph.
+
+To profile the entire test suite running this:
+
+```sh
+cd packages/lde
+lde run --profile --flamegraph -- -C ../.. test
+```
+
+This profiles the `lde` package entrypoint itself, not just an individual test file, and runs `lde test` as if it had been started from the repo root.
+
 ## Managing Dependencies
 
 Always use `lde add` / `lde remove` instead of manually editing `lde.json`. Manual edits leave `lde.lock` out of sync and can break installs.
@@ -382,9 +399,9 @@ The project was previously named `lpm`. You may see `lpm.json` or `lpm-test` ref
 
 **Windows:** The system GCC on `windows-latest` targets msvcrt, but lj-dist's `libluajit` is built against UCRT. This causes linker errors (`undefined reference to __imp_fseeko64` etc). CI downloads [llvm-mingw](https://github.com/mstorsjo/llvm-mingw) (a Clang/LLD MinGW-w64 toolchain targeting UCRT) and sets `SEA_CC`:
 
-| Runner | `SEA_CC` |
-|---|---|
-| `windows-latest` | `x86_64-w64-mingw32-clang` |
+| Runner           | `SEA_CC`                    |
+| ---------------- | --------------------------- |
+| `windows-latest` | `x86_64-w64-mingw32-clang`  |
 | `windows-11-arm` | `aarch64-w64-mingw32-clang` |
 
-**Android:** Android uses Bionic rather than glibc. The binary is compiled on the host using the Android NDK's clang (`aarch64-linux-android21-clang`), which links against Bionic. Tests run inside a Termux Docker container (`termux/termux-docker:aarch64` under QEMU on the ARM64 runner), which provides a matching Bionic environment.
+**Android:** Android uses Bionic rather than glibc. The binary is compiled on the host using the Android NDK's clang (`aarch64-linux-android21-clang`), which links against Bionic. Tests run inside a Termux Docker container (`termux/termux-docker:aarch64` under QEMU on the ARM64 runner), which provides a matching Bionic environment.

packages/clap/src/init.lua

@@ -33,7 +33,7 @@ function Args:option(desiredKey)
 			else
 				local key = string.sub(raw, 3)
 
-				if key == desiredKey and self.raw[i + 1] ~= nil then
+				if key == desiredKey and self.raw[i + 1] ~= nil and self.raw[i + 1] ~= "--" then
 					local _key = table.remove(self.raw, i)
 					return table.remove(self.raw, i), i - 2
 				elseif key == "" then

packages/clap/tests/main.test.lua

@@ -0,0 +1,21 @@
+local test = require("lde-test")
+
+local clap = require("clap")
+
+test.it("option does not consume -- as a value", function()
+	local args = clap.parse({ "--profile", "--flamegraph", "--", "--cwd", "../..", "test" })
+
+	test.truthy(args:flag("profile"))
+	test.equal(args:option("flamegraph"), nil)
+	test.equal(args:peek(), "--flamegraph")
+
+	local dash, dashPos = args:flag("")
+	test.truthy(dash)
+	test.equal(dashPos, 1)
+
+	local rest = args:drain(dashPos)
+	test.equal(rest[1], "--flamegraph")
+	test.equal(rest[2], "--cwd")
+	test.equal(rest[3], "../..")
+	test.equal(rest[4], "test")
+end)

packages/fs/tests/fs.test.lua

@@ -425,14 +425,13 @@ test.it("watch recursive detects creation in newly created subdirectory", functi
 	local sub = path.join(d, "newdir")
 	fs.mkdir(sub)
 
-	-- Drain the mkdir event and let the watcher register the new subdir
-	local deadline = os.clock() + 1
-	while os.clock() < deadline do w.poll() end
+	-- Block on the mkdir event so the watcher can register the new subdir
+	w.wait()
 
 	local before = #events
 	fs.write(path.join(sub, "file.txt"), "hi")
 
-	deadline = os.clock() + 1
+	local deadline = os.clock() + 1
 	while #events == before and os.clock() < deadline do
 		w.poll()
 	end

packages/json/benchmarks/src/init.lua

@@ -45,9 +45,9 @@ end
 
 -- ── fixtures ──────────────────────────────────────────────────────────────────
 
-local SMALL = '{"name":"Alice","age":30,"active":true}'
+local SMALL     = '{"name":"Alice","age":30,"active":true}'
 
-local MEDIUM = json.encode({
+local MEDIUM    = json.encode({
 	users = (function()
 		local t = {}
 		for i = 1, 20 do
@@ -57,7 +57,7 @@ local MEDIUM = json.encode({
 	end)()
 })
 
-local LARGE = json.encode((function()
+local LARGE     = json.encode((function()
 	local t = {}
 	for i = 1, 500 do
 		t[i] = { id = i, name = "item" .. i, value = i * 3.14, tags = { "a", "b", "c" } }
@@ -77,41 +77,41 @@ local JSON5_SRC = [[{
 	ports: [8080, 8443,],
 }]]
 
-local SMALL_T  = json.decode(SMALL)
-local MEDIUM_T = json.decode(MEDIUM)
-local LARGE_T  = json.decode(LARGE)
-local JSON5_T  = json.decode(JSON5_SRC)
+local SMALL_T   = json.decode(SMALL)
+local MEDIUM_T  = json.decode(MEDIUM)
+local LARGE_T   = json.decode(LARGE)
+local JSON5_T   = json.decode(JSON5_SRC)
 
 -- ── run ───────────────────────────────────────────────────────────────────────
 
 ansi.printf("\n{bold}json decode{reset}")
-bench("small object (~40 B)",    function() json.decode(SMALL)     end, 5000)
-bench("medium array (~20 objs)", function() json.decode(MEDIUM)    end, 500)
-bench("large array (~500 objs)", function() json.decode(LARGE)     end, 20)
-bench("json5 with comments",     function() json.decode(JSON5_SRC) end, 2000)
+bench("small object (~40 B)", function() json.decode(SMALL) end, 5000)
+bench("medium array (~20 objs)", function() json.decode(MEDIUM) end, 500)
+bench("large array (~500 objs)", function() json.decode(LARGE) end, 20)
+bench("json5 with comments", function() json.decode(JSON5_SRC) end, 2000)
 
 ansi.printf("\n{bold}json encode{reset}")
-bench("small object",            function() json.encode(SMALL_T)  end, 5000)
-bench("medium array",            function() json.encode(MEDIUM_T) end, 500)
-bench("large array",             function() json.encode(LARGE_T)  end, 20)
-bench("json5 round-trip",        function() json.encode(JSON5_T)  end, 2000)
+bench("small object", function() json.encode(SMALL_T) end, 5000)
+bench("medium array", function() json.encode(MEDIUM_T) end, 500)
+bench("large array", function() json.encode(LARGE_T) end, 20)
+bench("json5 round-trip", function() json.encode(JSON5_T) end, 2000)
 
 ansi.printf("\n{bold}json round-trip (decode + encode){reset}")
-bench("small",  function() json.encode(json.decode(SMALL))  end, 5000)
+bench("small", function() json.encode(json.decode(SMALL)) end, 5000)
 bench("medium", function() json.encode(json.decode(MEDIUM)) end, 500)
-bench("large",  function() json.encode(json.decode(LARGE))  end, 20)
+bench("large", function() json.encode(json.decode(LARGE)) end, 20)
 
 ansi.printf("\n{bold}json decodeDocument only (zero-alloc){reset}")
-bench("small",  function() json.decodeDocument(SMALL)  end, 5000)
+bench("small", function() json.decodeDocument(SMALL) end, 5000)
 bench("medium", function() json.decodeDocument(MEDIUM) end, 500)
-bench("large",  function() json.decode(LARGE)  end, 20)
+bench("large", function() json.decodeDocument(LARGE) end, 20)
 
 ansi.printf("\n{bold}cjson decode{reset}")
-bench("small object (~40 B)",    function() cjson.decode(SMALL)  end, 5000)
+bench("small object (~40 B)", function() cjson.decode(SMALL) end, 5000)
 bench("medium array (~20 objs)", function() cjson.decode(MEDIUM) end, 500)
-bench("large array (~500 objs)", function() cjson.decode(LARGE)  end, 20)
+bench("large array (~500 objs)", function() cjson.decode(LARGE) end, 20)
 
 ansi.printf("\n{bold}cjson encode{reset}")
-bench("small object",  function() cjson.encode(cjson.decode(SMALL))  end, 5000)
-bench("medium array",  function() cjson.encode(cjson.decode(MEDIUM)) end, 500)
-bench("large array",   function() cjson.encode(cjson.decode(LARGE))  end, 20)
+bench("small object", function() cjson.encode(cjson.decode(SMALL)) end, 5000)
+bench("medium array", function() cjson.encode(cjson.decode(MEDIUM)) end, 500)
+bench("large array", function() cjson.encode(cjson.decode(LARGE)) end, 20)

packages/json/src/init.lua

@@ -339,8 +339,6 @@ putValue    = function(tape, v, indent, level, valueStyle)
 			tape:put("Infinity")
 		elseif v == -huge then
 			tape:put("-Infinity")
-		elseif v == floor(v) then
-			tape:put(string.format("%d", v))
 		else
 			tape:put(tostring(v))
 		end
@@ -784,17 +782,17 @@ local function materialise(doc, idx)
 		end
 		return arr
 	elseif ty == TY_OBJECT then
-		local obj  = {}
-		local keys = {}
+		local obj     = {}
+		local keys    = {}
 		keyStore[obj] = keys
 		local ki      = tok.child
 		while ki ~= 0 do
-			src_s    = doc.src; src_ptr = cast(u8p, src_s); src_len = #src_s
-			local k  = tokToString(doc.toks[ki])
-			local vi = doc.toks[ki].next
-			obj[k]   = materialise(doc, vi)
+			src_s           = doc.src; src_ptr = cast(u8p, src_s); src_len = #src_s
+			local k         = tokToString(doc.toks[ki])
+			local vi        = doc.toks[ki].next
+			obj[k]          = materialise(doc, vi)
 			keys[#keys + 1] = k
-			ki = doc.toks[vi].next
+			ki              = doc.toks[vi].next
 		end
 		return obj
 	end