Analyzers and AST Rewriting

## What ParseFile does `go/parser.ParseFile` turns the bytes of a single Go source file into a tree of `go/ast` nodes. Its signature is: ```go func ParseFile(fset *token.FileSet, filename string, src any, mode Mode) (*ast.File, error) ``` - **`fset`** — the `*token.FileSet` the new file is registered in. It must not be nil. - **`filename`** — recorded in the FileSet and used in error messages. If `src` is nil, the parser reads this path from disk; otherwise the name is purely a label. - **`src`** — nil, a `string`, a `[]byte`, or an `io.Reader` holding the source text. - **`mode`** — parser flags. `parser.ParseComments` keeps comments in the tree (without it they are thrown away). `parser.AllErrors` reports every syntax error instead of stopping after a handful. `parser.ImportsOnly` and `parser.PackageClauseOnly` stop parsing early when you only need the file's header. `parser.SkipObjectResolution` skips building the old identifier-resolution data, which is faster and is what you want when you will do your own name resolution or a type-checked pass. The result is an `*ast.File` with fields such as `Name` (the package identifier), `Decls` (top-level declarations), `Imports`, `Doc` (the package doc comment) and `Comments` (every comment group in the file). If the source could not be read at all you get a nil file; if it read but did not parse, you get a **partial tree plus an error**, and that error is a `scanner.ErrorList` you can iterate for individual positions and messages. Deciding whether to work with a partial tree or bail out is your call. One thing `ParseFile` deliberately does not do is type-check. It has no idea what any identifier refers to, what a package's exported names are, or whether the code compiles. Undefined names, wrong argument counts and type mismatches are not syntax errors and will not be reported. ## Why a FileSet exists Every AST node implements `Pos() token.Pos` and `End() token.Pos`. A `token.Pos` is a single integer, and that is a deliberate space optimisation — nodes are tiny and there are millions of them. The integer is **not** an offset within its own file. It is an index into one continuous address space that the FileSet hands out: the first file gets a base, the file occupies `size+1` values, the next file starts after it, and so on. Because the ranges do not overlap, a Pos identifies its file implicitly. The FileSet is the only thing that can decode that. It stores, per file, the name, the base, the size and the table of line-start offsets. So: ```go pos := fset.Position(node.Pos()) // pos.Filename, pos.Offset (byte index in that file), pos.Line, pos.Column ``` `fset.File(p)` gives you the `*token.File` a position belongs to, and `fset.PositionFor(p, adjusted)` lets you choose whether `//line` directives (used by code generators to point at their input) are applied. `token.NoPos` is the zero value and means "no position" — synthesised nodes you build yourself have it. The practical rules that follow: 1. **Create one FileSet per run** with `token.NewFileSet()` and parse every file into it. Do not make a fresh one per file or per print call. 2. **Never mix FileSets.** A Pos from one and a `Position` call on another yields the wrong file or nonsense; nothing panics, so the bug shows up as garbage line numbers. 3. **Keep the FileSet as long as you keep the tree.** Printing the tree back out with `go/format.Node(w, fset, file)` needs it, because the printer places comments and blank lines using the recorded positions. 4. **`Position.Offset` is your bridge to raw bytes.** If you also keep the original source, offsets let you splice text directly instead of re-printing the whole file — which is how you keep untouched lines byte-identical in a large mechanical change. ## A minimal pass ```go fset := token.NewFileSet() file, err := parser.ParseFile(fset, path, nil, parser.ParseComments) if err != nil { return err } ast.Inspect(file, func(n ast.Node) bool { if fn, ok := n.(*ast.FuncDecl); ok { fmt.Println(fset.Position(fn.Pos()), fn.Name.Name) } return true }) ``` That prints something of the form `path/to/file.go:12:1 Handler` for each function declaration — the FileSet is what makes the human-readable half of that line possible. ## Where this sits `go/parser` and `go/ast` are syntax only. `go/token` supplies positions. `go/format` prints a tree back as gofmt-formatted source. When you need to know what a name *means* — which package a selector resolves to, what type an expression has — you move up to a type-checked load, which reuses exactly the same `token.FileSet` and `*ast.File` values, so nothing you learn here is thrown away.