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.
This commit is contained in:
sam committed 2026-09-22 00:26:18 +10:00
1 parent edce8fa1d8
commit 3242e537e2
5 files changed
+109 -38

No files matched your search

+15
View File
@@ -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 ./...
+25
View File
@@ -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)
}
})
}
}
+54 -34
View File
@@ -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
+1 -1
View File
@@ -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,
)
}
+14 -3
View File
@@ -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
}