From 3242e537e2be03f1b606bb7aa1f2d8ffdc599985 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Tue, 22 Sep 2026 00:26:18 +1000 Subject: [PATCH] build(tools): lint the tools module in the gate golangci-lint ran ./... from the repository root, which stops at the root module, so the tools module was never linted and had drifted unseen. task check already closes this hole for tests with test:tools; lint now has the same shape in lint:tools, which runs in the tools directory rather than passing a path prefix that only rewrites output paths. Fixes the six issues that had accumulated behind it: stripJSComments was 21 cyclomatic complexity against a cap of 15, with the comment-skipping and literal-copying loops inlined into one scanner. It is four named functions now, and the De Morgan warning went with the rewrite. It had no test despite deciding whether a commented-out call reads as a live consumer, so it has one: literals that look like comments, comment markers inside strings, escapes, and unterminated literals and block comments. docsgen's missing-artifact error ended in punctuation, and three test type assertions were unchecked, which panic rather than fail when the generated artifact does not have the shape the case assumes. --- Taskfile.yml | 15 ++++++ tools/contractaudit/audit_test.go | 25 +++++++++ tools/contractaudit/webui.go | 88 +++++++++++++++++++------------ tools/docsgen/main.go | 2 +- tools/docsgen/main_test.go | 17 ++++-- 5 files changed, 109 insertions(+), 38 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index 341b76820..82326fe90 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -88,6 +88,21 @@ tasks: lint: desc: Run golangci-lint + summary: | + Both modules. ./... from the root stops at the root module, so the tools + module was never linted and drifted unseen -- the same hole task check + already closes for tests with test:tools. + cmds: + - golangci-lint run ./... + - task: lint:tools + + lint:tools: + desc: Run golangci-lint over the tools module + summary: | + ./... from the root stops at the root module, so the tools module was + never linted and drifted unseen -- the same hole task check already + closes for tests with test:tools. + dir: tools cmds: - golangci-lint run ./... diff --git a/tools/contractaudit/audit_test.go b/tools/contractaudit/audit_test.go index 5f77499bb..6ce31036a 100644 --- a/tools/contractaudit/audit_test.go +++ b/tools/contractaudit/audit_test.go @@ -131,3 +131,28 @@ func TestParseDeclarations(t *testing.T) { } }) } + +// TestStripJSComments pins the behaviour the extractor depends on: a commented +// call must not read as a live consumer, and a literal that merely looks like a +// comment must survive intact. +func TestStripJSComments(t *testing.T) { + for _, tc := range []struct{ name, src, want string }{ + {"line comment goes", "a // gone\nb", "a \nb"}, + {"newline survives a line comment", "a // gone\nb", "a \nb"}, + {"block comment goes", "a/* gone */b", "ab"}, + {"unterminated block comment eats the tail", "a/* gone", "a"}, + {"comment marker inside a string survives", `f("// not a comment")`, `f("// not a comment")`}, + {"block marker inside a string survives", `f("/* kept */")`, `f("/* kept */")`}, + {"template literal survives", "f(`/* kept */`)", "f(`/* kept */`)"}, + {"escaped quote does not end the literal", `f("a\"// kept")`, `f("a\"// kept")`}, + {"unterminated literal keeps its tail", `f("abc`, `f("abc`}, + {"adjacent literals", `a("x")+b('y')`, `a("x")+b('y')`}, + {"code either side of a block comment", "a/*x*/b/*y*/c", "abc"}, + } { + t.Run(tc.name, func(t *testing.T) { + if got := stripJSComments(tc.src); got != tc.want { + t.Fatalf("stripJSComments(%q) = %q, want %q", tc.src, got, tc.want) + } + }) + } +} diff --git a/tools/contractaudit/webui.go b/tools/contractaudit/webui.go index 1a596c145..31d13dbae 100644 --- a/tools/contractaudit/webui.go +++ b/tools/contractaudit/webui.go @@ -217,49 +217,69 @@ func scanFile(rel, body string) ([]string, error) { func stripJSComments(src string) string { var b strings.Builder b.Grow(len(src)) - var quote byte for i := 0; i < len(src); { - c := src[i] - var next byte - if i+1 < len(src) { - next = src[i+1] - } - if quote != 0 { - b.WriteByte(c) - if c == '\\' && i+1 < len(src) { - b.WriteByte(next) - i += 2 - continue - } - if c == quote { - quote = 0 - } - i++ - continue - } switch { - case c == '"' || c == '\'' || c == '`': - quote = c - b.WriteByte(c) - i++ - case c == '/' && next == '/': - for i < len(src) && src[i] != '\n' { - i++ - } - case c == '/' && next == '*': - i += 2 - for i < len(src) && !(src[i] == '*' && i+1 < len(src) && src[i+1] == '/') { - i++ - } - i += 2 + case opensComment(src, i, '/'): + i = skipLineComment(src, i) + case opensComment(src, i, '*'): + i = skipBlockComment(src, i) + case src[i] == '"' || src[i] == '\'' || src[i] == '`': + i = copyLiteral(&b, src, i) default: - b.WriteByte(c) + b.WriteByte(src[i]) i++ } } return b.String() } +// opensComment reports whether a comment introduced by "/" plus second opens +// at i. +func opensComment(src string, i int, second byte) bool { + return src[i] == '/' && i+1 < len(src) && src[i+1] == second +} + +// skipLineComment returns the index of the newline that ends the // comment at +// i, leaving the newline itself to be copied: dropping it would join two +// statements into one line. +func skipLineComment(src string, i int) int { + for i < len(src) && src[i] != '\n' { + i++ + } + return i +} + +// skipBlockComment returns the index just past the "*/" closing the comment at +// i, or the end of src when the comment is unterminated. +func skipBlockComment(src string, i int) int { + for i += 2; i < len(src); i++ { + if src[i] == '*' && i+1 < len(src) && src[i+1] == '/' { + return i + 2 + } + } + return i +} + +// copyLiteral copies the string, template or regex literal opening at i, +// escapes included, and returns the index just past its closing quote. An +// unterminated literal copies to the end rather than discarding the tail. +func copyLiteral(b *strings.Builder, src string, i int) int { + quote := src[i] + b.WriteByte(quote) + for i++; i < len(src); i++ { + b.WriteByte(src[i]) + if src[i] == '\\' && i+1 < len(src) { + i++ + b.WriteByte(src[i]) + continue + } + if src[i] == quote { + return i + 1 + } + } + return i +} + // normalizeRoute strips query strings and replaces both `${...}` template // interpolations and `{param}` wildcards with a single placeholder, so a // parameter's *name* never causes a false mismatch. `{id}` in the server and diff --git a/tools/docsgen/main.go b/tools/docsgen/main.go index 110adab8d..aa23a7ed5 100644 --- a/tools/docsgen/main.go +++ b/tools/docsgen/main.go @@ -135,7 +135,7 @@ func check(repoRoot, outPath string) error { committed, err := os.ReadFile(committedPath) if errors.Is(err, fs.ErrNotExist) { return fmt.Errorf( - "%s is missing; regenerate it with: go -C tools run ./docsgen --repo-root ..", + "%s is missing; regenerate it by running `go -C tools run ./docsgen --repo-root ..` from the tools module", relative, ) } diff --git a/tools/docsgen/main_test.go b/tools/docsgen/main_test.go index e23c6a13c..93a5b0372 100644 --- a/tools/docsgen/main_test.go +++ b/tools/docsgen/main_test.go @@ -195,8 +195,8 @@ func TestCheckReportsChangedSchema(t *testing.T) { t.Fatalf("run() error = %v", err) } mutateGeneratedData(t, output, func(data map[string]any) { - schemas := data["schemas"].(map[string]any) - schemas["AgentExecutionResult"].(map[string]any)["title"] = "tampered" + schemas := mapAt(t, data, "schemas") + mapAt(t, schemas, "AgentExecutionResult")["title"] = "tampered" }) err := check(repoRoot, output) @@ -217,7 +217,7 @@ func TestCheckReportsRemovedSchema(t *testing.T) { t.Fatalf("run() error = %v", err) } mutateGeneratedData(t, output, func(data map[string]any) { - delete(data["schemas"].(map[string]any), "MessageEvent") + delete(mapAt(t, data, "schemas"), "MessageEvent") }) err := check(repoRoot, output) @@ -505,3 +505,14 @@ func walkJSON(value any, visitRef func(string)) { } } } + +// mapAt returns the nested object at key, failing the test rather than panicking +// when the generated artifact does not have the shape the case assumes. +func mapAt(t *testing.T, parent map[string]any, key string) map[string]any { + t.Helper() + child, ok := parent[key].(map[string]any) + if !ok { + t.Fatalf("%s is %T, want an object", key, parent[key]) + } + return child +}