From 9245a39677d8f8e5c21e28f230d42c147994258e Mon Sep 17 00:00:00 2001
From: "svc-finitelabs[bot]"
 <269744575+svc-finitelabs[bot]@users.noreply.github.com>
Date: Sat, 8 Aug 2026 12:46:31 -0500
Subject: [PATCH] build: typecheck the whole workspace against a committed
 config

`Int64HighLow` was defined in both `src/crypto/annotations.lua` and
`vendor/bitn.lua`, so an editor with the repository open reported
`duplicate-doc-alias` on each while `make typecheck` saw neither.

Dropping the duplicate on its own regresses the check. `typecheck` ran
`--check "$(CURDIR)/src"`, which never scans `vendor/`, so removing the
alias from annotations.lua takes the run from 11 problems to 57: the 46
`undefined-doc-name` reports that annotations.lua was added to eliminate.

The duplicate is a symptom; the scope mismatch is the cause. An editor
opens the repository as its workspace, and `@alias` resolves
workspace-wide, so a narrower scope does not yield a subset of the
findings, it yields a different set.

Widening the scope alone still leaves the count unreproducible, because
`.luarc.json` is matched by a global gitignore and has never been in the
repository, so the target read whichever private config the developer
happened to have. `runtime.version` is what moved the number: unset it
defaults to Lua 5.4 and `vendor/bitn.lua` is clean, while `LuaJIT`, the
runtime this library actually targets, reports 7 of its own.

So the config is committed and the target pins it with `--configpath`,
leaving `.luarc.json` as personal editor preference. `vendor` is listed
as a `workspace.library` and in `ignoreDir`: as a library its `@alias`
definitions still resolve, and via ignoreDir its files are not diagnosed.
Either half alone is wrong (ignoreDir without library loses the
definitions and returns to 57; library without ignoreDir reports 18).

  11 problems in 3 files, all in src/, reproducible regardless of any
  local .luarc.json, on lua-language-server 3.19.0

The target now prints the server version, because the remaining 11 are
tool-version sensitive.

Verified: `make typecheck` 11 problems in 3 files, the same
param-type-mismatch set as the previous baseline; `./run_tests.sh` 15/15
modules; `make format-check` clean. `make lint` was not runnable here
(luacheck 1.2.0 fails under this host's Lua 5.5, in its own
standards.lua); CI's luacheck leg is unaffected.

FL-4
---
 .luarc-typecheck.json      |  9 +++++++++
 Makefile                   | 10 ++++++++--
 src/crypto/annotations.lua |  9 +++++----
 3 files changed, 22 insertions(+), 6 deletions(-)
 create mode 100644 .luarc-typecheck.json

diff --git a/.luarc-typecheck.json b/.luarc-typecheck.json
new file mode 100644
index 0000000..e902932
--- /dev/null
+++ b/.luarc-typecheck.json
@@ -0,0 +1,9 @@
+{
+  "runtime": { "version": "LuaJIT" },
+  "workspace": {
+    "useGitIgnore": false,
+    "library": ["vendor"],
+    "ignoreDir": [".claude", ".git", ".idea", ".venv", "build", "dist", "node_modules", "vendor"]
+  },
+  "diagnostics": { "disable": ["unnecessary-assert"] }
+}
diff --git a/Makefile b/Makefile
index ef17773..4610957 100644
--- a/Makefile
+++ b/Makefile
@@ -167,11 +167,17 @@ lint:
 # Deliberately NOT part of `check`: a handful of type-narrowing and
 # deliberate-bad-argument diagnostics remain, and turning CI red on those is a
 # separate decision from making the check runnable.
+#
+# Checks the whole repo, not just src/: an editor's workspace is the repo, and
+# @alias resolves workspace-wide, so a narrower scope gives different findings
+# rather than fewer. --configpath pins the config, because .luarc.json is
+# personal editor preference and the count moves with it.
 .PHONY: typecheck
 typecheck:
 	@if command -v lua-language-server >/dev/null 2>&1; then \
-		echo "Running lua-language-server..."; \
-		lua-language-server --check "$(CURDIR)/src" --checklevel=Warning --logpath="$(CURDIR)/build/luals"; \
+		echo "Running lua-language-server $$(lua-language-server --version)..."; \
+		lua-language-server --check "$(CURDIR)" --checklevel=Warning \
+			--configpath="$(CURDIR)/.luarc-typecheck.json" --logpath="$(CURDIR)/build/luals"; \
 	else \
 		echo "lua-language-server not found. Install with: make install-deps"; \
 		exit 1; \
diff --git a/src/crypto/annotations.lua b/src/crypto/annotations.lua
index 7585b0d..0ee6bb6 100644
--- a/src/crypto/annotations.lua
+++ b/src/crypto/annotations.lua
@@ -10,7 +10,8 @@
 --- `crypto.init`) does not bundle it and the shipped builds are unchanged.
 ---
 --- Do not add runtime code here. Types used by a single module stay in that
---- module, next to what they describe.
+--- module, next to what they describe, and a type already defined in `vendor/`
+--- stays there rather than being restated here.
 
 -- ----------------------------------------------------------------------------
 -- Curve25519 field arithmetic
@@ -27,6 +28,6 @@
 -- ----------------------------------------------------------------------------
 -- Lua 5.1/5.2 have no 64-bit integers and 5.3+ `//` semantics differ, so the
 -- 64-bit primitives (SHA-512, BLAKE2b) carry 64-bit quantities as a pair of
--- 32-bit halves. Used by `utils/bytes`, `sha512` and `blake2`.
-
---- @alias Int64HighLow { [1]: integer, [2]: integer } 64-bit value as {high, low} 32-bit halves
+-- 32-bit halves, used by `utils/bytes`, `sha512` and `blake2`.
+--
+-- Int64HighLow is defined in vendor/bitn.lua, where these halves come from.