Debian Codegraph @

debian/patches/0002-Add-local-copy-of-x-tools-go-expect.patch

raw
1 From: "Dr. Tobias Quathamer" <[email protected]>
2 Date: Mon, 23 Feb 2026 21:32:04 +0100
3 Subject: Add local copy of x/tools/go/expect
4
5 ---
6 golang-x-tools/expect/expect.go | 123 +++++++++++
7 golang-x-tools/expect/extract.go | 442 +++++++++++++++++++++++++++++++++++++++
8 2 files changed, 565 insertions(+)
9 create mode 100644 golang-x-tools/expect/expect.go
10 create mode 100644 golang-x-tools/expect/extract.go
11
12 diff --git a/golang-x-tools/expect/expect.go b/golang-x-tools/expect/expect.go
13 new file mode 100644
14 index 0000000..69875cd
15 --- /dev/null
16 +++ b/golang-x-tools/expect/expect.go
17 @@ -0,0 +1,123 @@
18 +// Copyright 2018 The Go Authors. All rights reserved.
19 +// Use of this source code is governed by a BSD-style
20 +// license that can be found in the LICENSE file.
21 +
22 +/*
23 +Package expect provides support for interpreting structured comments in Go
24 +source code (including go.mod and go.work files) as test expectations.
25 +
26 +This is primarily intended for writing tests of things that process Go source
27 +files, although it does not directly depend on the testing package.
28 +
29 +Collect notes with the Extract or Parse functions, and use the
30 +MatchBefore function to find matches within the lines the comments were on.
31 +
32 +The interpretation of the notes depends on the application.
33 +For example, the test suite for a static checking tool might
34 +use a @diag note to indicate an expected diagnostic:
35 +
36 + fmt.Printf("%s", 1) //@ diag("%s wants a string, got int")
37 +
38 +By contrast, the test suite for a source code navigation tool
39 +might use notes to indicate the positions of features of
40 +interest, the actions to be performed by the test,
41 +and their expected outcomes:
42 +
43 + var x = 1 //@ x_decl
44 + ...
45 + print(x) //@ definition("x", x_decl)
46 + print(x) //@ typeof("x", "int")
47 +
48 +# Note comment syntax
49 +
50 +Note comments always start with the special marker @, which must be the
51 +very first character after the comment opening pair, so //@ or /*@ with no
52 +spaces.
53 +
54 +This is followed by a comma separated list of notes.
55 +
56 +A note always starts with an identifier, which is optionally followed by an
57 +argument list. The argument list is surrounded with parentheses and contains a
58 +comma-separated list of arguments.
59 +The empty parameter list and the missing parameter list are distinguishable if
60 +needed; they result in a nil or an empty list in the Args parameter respectively.
61 +
62 +Arguments may be positional, such as f(value), or named, such as f(name=value).
63 +Positional arguments must appear before named arguments.
64 +Names may not be repeated.
65 +
66 +Argument values may be either identifiers or literals.
67 +The literals supported are the basic value literals, of string, float, integer
68 +true, false or nil. All the literals match the standard go conventions, with
69 +all bases of integers, and both quote and backtick strings.
70 +There is one extra literal type, which is a string literal preceded by the
71 +identifier "re" which is compiled to a regular expression.
72 +*/
73 +package expect
74 +
75 +import (
76 + "bytes"
77 + "fmt"
78 + "go/token"
79 + "regexp"
80 +)
81 +
82 +// Note is a parsed note from an expect comment.
83 +// It knows the position of the start of the comment, and the name and
84 +// arguments that make up the note.
85 +type Note struct {
86 + Pos token.Pos // The position at which the note identifier appears
87 + Name string // the name associated with the note
88 + Args []any // positional arguments (non-nil if parens were present)
89 + NamedArgs map[string]any // named arguments (or nil if none)
90 +}
91 +
92 +// ReadFile is the type of a function that can provide file contents for a
93 +// given filename.
94 +// This is used in MatchBefore to look up the content of the file in order to
95 +// find the line to match the pattern against.
96 +type ReadFile func(filename string) ([]byte, error)
97 +
98 +// MatchBefore attempts to match a pattern in the line before the supplied pos.
99 +// It uses the FileSet and the ReadFile to work out the contents of the line
100 +// that end is part of, and then matches the pattern against the content of the
101 +// start of that line up to the supplied position.
102 +// The pattern may be either a simple string, []byte or a *regexp.Regexp.
103 +// MatchBefore returns the range of the line that matched the pattern, and
104 +// invalid positions if there was no match, or an error if the line could not be
105 +// found.
106 +func MatchBefore(fset *token.FileSet, readFile ReadFile, end token.Pos, pattern any) (token.Pos, token.Pos, error) {
107 + f := fset.File(end)
108 + content, err := readFile(f.Name())
109 + if err != nil {
110 + return token.NoPos, token.NoPos, fmt.Errorf("invalid file: %v", err)
111 + }
112 + position := f.Position(end)
113 + startOffset := f.Offset(f.LineStart(position.Line))
114 + endOffset := f.Offset(end)
115 + line := content[startOffset:endOffset]
116 + matchStart, matchEnd := -1, -1
117 + switch pattern := pattern.(type) {
118 + case string:
119 + bytePattern := []byte(pattern)
120 + matchStart = bytes.Index(line, bytePattern)
121 + if matchStart >= 0 {
122 + matchEnd = matchStart + len(bytePattern)
123 + }
124 + case []byte:
125 + matchStart = bytes.Index(line, pattern)
126 + if matchStart >= 0 {
127 + matchEnd = matchStart + len(pattern)
128 + }
129 + case *regexp.Regexp:
130 + match := pattern.FindIndex(line)
131 + if len(match) > 0 {
132 + matchStart = match[0]
133 + matchEnd = match[1]
134 + }
135 + }
136 + if matchStart < 0 {
137 + return token.NoPos, token.NoPos, nil
138 + }
139 + return f.Pos(startOffset + matchStart), f.Pos(startOffset + matchEnd), nil
140 +}
141 diff --git a/golang-x-tools/expect/extract.go b/golang-x-tools/expect/extract.go
142 new file mode 100644
143 index 0000000..0c86273
144 --- /dev/null
145 +++ b/golang-x-tools/expect/extract.go
146 @@ -0,0 +1,442 @@
147 +// Copyright 2018 The Go Authors. All rights reserved.
148 +// Use of this source code is governed by a BSD-style
149 +// license that can be found in the LICENSE file.
150 +
151 +package expect
152 +
153 +import (
154 + "fmt"
155 + "go/ast"
156 + "go/parser"
157 + goscanner "go/scanner"
158 + "go/token"
159 + "os"
160 + "path/filepath"
161 + "regexp"
162 + "strconv"
163 + "strings"
164 + "text/scanner"
165 +
166 + "golang.org/x/mod/modfile"
167 +)
168 +
169 +const commentStart = "@"
170 +const commentStartLen = len(commentStart)
171 +
172 +// Identifier is the type for an identifier in a Note argument list.
173 +type Identifier string
174 +
175 +// Parse collects all the notes present in a file.
176 +// If content is nil, the filename specified is read and parsed, otherwise the
177 +// content is used and the filename is used for positions and error messages.
178 +// Each comment whose text starts with @ is parsed as a comma-separated
179 +// sequence of notes.
180 +// See the package documentation for details about the syntax of those
181 +// notes.
182 +func Parse(fset *token.FileSet, filename string, content []byte) ([]*Note, error) {
183 + if content == nil {
184 + data, err := os.ReadFile(filename)
185 + if err != nil {
186 + return nil, err
187 + }
188 + content = data
189 + }
190 +
191 + switch filepath.Ext(filename) {
192 + case ".s":
193 + // The assembler uses a custom scanner,
194 + // but the go/scanner package is close
195 + // enough: we only want the comments.
196 + file := fset.AddFile(filename, -1, len(content))
197 + var scan goscanner.Scanner
198 + scan.Init(file, content, nil, goscanner.ScanComments)
199 +
200 + var notes []*Note
201 + for {
202 + pos, tok, lit := scan.Scan()
203 + if tok == token.EOF {
204 + break
205 + }
206 + if tok == token.COMMENT {
207 + text, adjust := getAdjustedNote(lit)
208 + if text == "" {
209 + continue
210 + }
211 + parsed, err := parse(fset, pos+token.Pos(adjust), text)
212 + if err != nil {
213 + return nil, err
214 + }
215 + notes = append(notes, parsed...)
216 + }
217 + }
218 + return notes, nil
219 +
220 + case ".go":
221 + // TODO: We should write this in terms of the scanner, like the .s case above.
222 + // there are ways you can break the parser such that it will not add all the
223 + // comments to the ast, which may result in files where the tests are silently
224 + // not run.
225 + file, err := parser.ParseFile(fset, filename, content, parser.ParseComments|parser.AllErrors|parser.SkipObjectResolution)
226 + if file == nil {
227 + return nil, err
228 + }
229 + return ExtractGo(fset, file)
230 +
231 + case ".mod":
232 + file, err := modfile.Parse(filename, content, nil)
233 + if err != nil {
234 + return nil, err
235 + }
236 + f := fset.AddFile(filename, -1, len(content))
237 + f.SetLinesForContent(content)
238 + notes, err := extractModWork(fset, file.Syntax.Stmt)
239 + if err != nil {
240 + return nil, err
241 + }
242 + // Since modfile.Parse does not return an *ast, we need to add the offset
243 + // within the file's contents to the file's base relative to the fileset.
244 + for _, note := range notes {
245 + note.Pos += token.Pos(f.Base())
246 + }
247 + return notes, nil
248 +
249 + case ".work":
250 + file, err := modfile.ParseWork(filename, content, nil)
251 + if err != nil {
252 + return nil, err
253 + }
254 + f := fset.AddFile(filename, -1, len(content))
255 + f.SetLinesForContent(content)
256 + notes, err := extractModWork(fset, file.Syntax.Stmt)
257 + if err != nil {
258 + return nil, err
259 + }
260 + // As with go.mod files, we need to compute a synthetic token.Pos.
261 + for _, note := range notes {
262 + note.Pos += token.Pos(f.Base())
263 + }
264 + return notes, nil
265 + }
266 + return nil, nil
267 +}
268 +
269 +// extractModWork collects all the notes present in a go.mod file or go.work
270 +// file, by way of the shared modfile.Expr statement node.
271 +//
272 +// Each comment whose text starts with @ is parsed as a comma-separated
273 +// sequence of notes.
274 +// See the package documentation for details about the syntax of those
275 +// notes.
276 +// Only allow notes to appear with the following format: "//@mark()" or // @mark()
277 +func extractModWork(fset *token.FileSet, exprs []modfile.Expr) ([]*Note, error) {
278 + var notes []*Note
279 + for _, stmt := range exprs {
280 + comment := stmt.Comment()
281 + if comment == nil {
282 + continue
283 + }
284 + var allComments []modfile.Comment
285 + allComments = append(allComments, comment.Before...)
286 + allComments = append(allComments, comment.Suffix...)
287 + for _, cmt := range allComments {
288 + text, adjust := getAdjustedNote(cmt.Token)
289 + if text == "" {
290 + continue
291 + }
292 + parsed, err := parse(fset, token.Pos(int(cmt.Start.Byte)+adjust), text)
293 + if err != nil {
294 + return nil, err
295 + }
296 + notes = append(notes, parsed...)
297 + }
298 + }
299 + return notes, nil
300 +}
301 +
302 +// ExtractGo collects all the notes present in an AST.
303 +// Each comment whose text starts with @ is parsed as a comma-separated
304 +// sequence of notes.
305 +// See the package documentation for details about the syntax of those
306 +// notes.
307 +func ExtractGo(fset *token.FileSet, file *ast.File) ([]*Note, error) {
308 + var notes []*Note
309 + for _, g := range file.Comments {
310 + for _, c := range g.List {
311 + text, adjust := getAdjustedNote(c.Text)
312 + if text == "" {
313 + continue
314 + }
315 + parsed, err := parse(fset, token.Pos(int(c.Pos())+adjust), text)
316 + if err != nil {
317 + return nil, err
318 + }
319 + notes = append(notes, parsed...)
320 + }
321 + }
322 + return notes, nil
323 +}
324 +
325 +func getAdjustedNote(text string) (string, int) {
326 + if strings.HasPrefix(text, "/*") {
327 + text = strings.TrimSuffix(text, "*/")
328 + }
329 + text = text[2:] // remove "//" or "/*" prefix
330 +
331 + // Allow notes to appear within comments.
332 + // For example:
333 + // "// //@mark()" is valid.
334 + // "// @mark()" is not valid.
335 + // "// /*@mark()*/" is not valid.
336 + var adjust int
337 + if i := strings.Index(text, commentStart); i > 2 {
338 + // Get the text before the commentStart.
339 + pre := text[i-2 : i]
340 + if pre != "//" {
341 + return "", 0
342 + }
343 + text = text[i:]
344 + adjust = i
345 + }
346 + if !strings.HasPrefix(text, commentStart) {
347 + return "", 0
348 + }
349 + text = text[commentStartLen:]
350 + return text, commentStartLen + adjust + 1
351 +}
352 +
353 +const invalidToken rune = 0
354 +
355 +type tokens struct {
356 + scanner scanner.Scanner
357 + current rune
358 + err error
359 + base token.Pos
360 +}
361 +
362 +func (t *tokens) Init(base token.Pos, text string) *tokens {
363 + t.base = base
364 + t.scanner.Init(strings.NewReader(text))
365 + t.scanner.Mode = scanner.GoTokens
366 + t.scanner.Whitespace ^= 1 << '\n' // don't skip new lines
367 + t.scanner.Error = func(s *scanner.Scanner, msg string) {
368 + t.Errorf("%v", msg)
369 + }
370 + return t
371 +}
372 +
373 +func (t *tokens) Consume() string {
374 + t.current = invalidToken
375 + return t.scanner.TokenText()
376 +}
377 +
378 +func (t *tokens) Token() rune {
379 + if t.err != nil {
380 + return scanner.EOF
381 + }
382 + if t.current == invalidToken {
383 + t.current = t.scanner.Scan()
384 + }
385 + return t.current
386 +}
387 +
388 +func (t *tokens) Skip(r rune) int {
389 + i := 0
390 + for t.Token() == '\n' {
391 + t.Consume()
392 + i++
393 + }
394 + return i
395 +}
396 +
397 +func (t *tokens) TokenString() string {
398 + return scanner.TokenString(t.Token())
399 +}
400 +
401 +func (t *tokens) Pos() token.Pos {
402 + return t.base + token.Pos(t.scanner.Position.Offset)
403 +}
404 +
405 +func (t *tokens) Errorf(msg string, args ...any) {
406 + if t.err != nil {
407 + return
408 + }
409 + t.err = fmt.Errorf(msg, args...)
410 +}
411 +
412 +func parse(fset *token.FileSet, base token.Pos, text string) ([]*Note, error) {
413 + t := new(tokens).Init(base, text)
414 + notes := parseComment(t)
415 + if t.err != nil {
416 + return nil, fmt.Errorf("%v: %s", fset.Position(t.Pos()), t.err)
417 + }
418 + return notes, nil
419 +}
420 +
421 +func parseComment(t *tokens) []*Note {
422 + var notes []*Note
423 + for {
424 + t.Skip('\n')
425 + switch t.Token() {
426 + case scanner.EOF:
427 + return notes
428 + case scanner.Ident:
429 + notes = append(notes, parseNote(t))
430 + default:
431 + t.Errorf("unexpected %s parsing comment, expect identifier", t.TokenString())
432 + return nil
433 + }
434 + switch t.Token() {
435 + case scanner.EOF:
436 + return notes
437 + case ',', '\n':
438 + t.Consume()
439 + default:
440 + t.Errorf("unexpected %s parsing comment, expect separator", t.TokenString())
441 + return nil
442 + }
443 + }
444 +}
445 +
446 +func parseNote(t *tokens) *Note {
447 + n := &Note{
448 + Pos: t.Pos(),
449 + Name: t.Consume(),
450 + }
451 +
452 + switch t.Token() {
453 + case ',', '\n', scanner.EOF:
454 + // no argument list present
455 + return n
456 + case '(':
457 + n.Args, n.NamedArgs = parseArgumentList(t)
458 + return n
459 + default:
460 + t.Errorf("unexpected %s parsing note", t.TokenString())
461 + return nil
462 + }
463 +}
464 +
465 +func parseArgumentList(t *tokens) (args []any, named map[string]any) {
466 + args = []any{} // @name() is represented by a non-nil empty slice.
467 + t.Consume() // '('
468 + t.Skip('\n')
469 + for t.Token() != ')' {
470 + name, arg := parseArgument(t)
471 + if name != "" {
472 + // f(k=v)
473 + if named == nil {
474 + named = make(map[string]any)
475 + }
476 + if _, dup := named[name]; dup {
477 + t.Errorf("duplicate named argument %q", name)
478 + return nil, nil
479 + }
480 + named[name] = arg
481 + } else {
482 + // f(v)
483 + if named != nil {
484 + t.Errorf("positional argument follows named argument")
485 + return nil, nil
486 + }
487 + args = append(args, arg)
488 + }
489 + if t.Token() != ',' {
490 + break
491 + }
492 + t.Consume()
493 + t.Skip('\n')
494 + }
495 + if t.Token() != ')' {
496 + t.Errorf("unexpected %s parsing argument list", t.TokenString())
497 + return nil, nil
498 + }
499 + t.Consume() // ')'
500 + return args, named
501 +}
502 +
503 +// parseArgument returns the value of the argument ("f(value)"),
504 +// and its name if named "f(name=value)".
505 +func parseArgument(t *tokens) (name string, value any) {
506 +again:
507 + switch t.Token() {
508 + case scanner.Ident:
509 + v := t.Consume()
510 + switch v {
511 + case "true":
512 + value = true
513 + case "false":
514 + value = false
515 + case "nil":
516 + value = nil
517 + case "re":
518 + if t.Token() != scanner.String && t.Token() != scanner.RawString {
519 + t.Errorf("re must be followed by string, got %s", t.TokenString())
520 + return
521 + }
522 + pattern, _ := strconv.Unquote(t.Consume()) // can't fail
523 + re, err := regexp.Compile(pattern)
524 + if err != nil {
525 + t.Errorf("invalid regular expression %s: %v", pattern, err)
526 + return
527 + }
528 + value = re
529 + default:
530 + // f(name=value)?
531 + if name == "" && t.Token() == '=' {
532 + t.Consume() // '='
533 + name = v
534 + goto again
535 + }
536 + value = Identifier(v)
537 + }
538 +
539 + case scanner.String, scanner.RawString:
540 + value, _ = strconv.Unquote(t.Consume()) // can't fail
541 +
542 + case scanner.Int:
543 + s := t.Consume()
544 + v, err := strconv.ParseInt(s, 0, 0)
545 + if err != nil {
546 + t.Errorf("cannot convert %v to int: %v", s, err)
547 + }
548 + value = v
549 +
550 + case scanner.Float:
551 + s := t.Consume()
552 + v, err := strconv.ParseFloat(s, 64)
553 + if err != nil {
554 + t.Errorf("cannot convert %v to float: %v", s, err)
555 + }
556 + value = v
557 +
558 + case '-':
559 + t.Consume()
560 + switch t.Token() {
561 + case scanner.Int:
562 + s := "-" + t.Consume()
563 + v, err := strconv.ParseInt(s, 0, 0)
564 + if err != nil {
565 + t.Errorf("cannot convert %v to int: %v", s, err)
566 + }
567 + value = v
568 +
569 + case scanner.Float:
570 + s := "-" + t.Consume()
571 + v, err := strconv.ParseFloat(s, 64)
572 + if err != nil {
573 + t.Errorf("cannot convert %v to float: %v", s, err)
574 + }
575 + value = v
576 +
577 + default:
578 + t.Errorf("unexpected '-' not followed by number, got %s", t.TokenString())
579 + }
580 +
581 + case scanner.Char:
582 + t.Errorf("unexpected char literal %s", t.Consume())
583 +
584 + default:
585 + t.Errorf("unexpected %s parsing argument", t.TokenString())
586 + }
587 + return
588 +}