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:
1 parent
95743b60cc
commit
959cf45ae2
5 files changed
+109
-38
No files matched your search
@@ -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 ./...
|
||||
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
|
||||
@@ -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,
|
||||
)
|
||||
}
|
||||
|
||||
@@ -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
|
||||
}
|
||||
Reference in new issue
Block a user