Documentation
¶
Overview ¶
Package codemod rewrites project code when an incompatible change of kit arrives.
A codemod belongs to the platform version that brings the change. apply runs the ones newer than the version the project was last applied with, which platformgo.lock records, so an upgrade over several versions replays every step in order. A codemod must be idempotent: code that has nothing left to rewrite stays as it is.
What a machine cannot rewrite goes to a person as a note: File.Report. Notes of Fix are printed by plan and apply once, when the codemod runs. Check finds code that can no longer compile with the version, such as a reference to a removed name, and runs on every plan and verify, so the note stays open until somebody fixes the code.
Index ¶
- Constants
- type Change
- type Codemod
- type File
- func (f *File) ImportName(path string) (string, bool)
- func (f *File) PackageImports(path string) bool
- func (f *File) PackageRef(e ast.Expr, pkg string) (*ast.SelectorExpr, bool)
- func (f *File) Replace(n ast.Node, text string)
- func (f *File) ReplaceRange(from, to token.Pos, text string)
- func (f *File) Report(n ast.Node, msg string)
- func (f *File) Source(n ast.Node) string
- type Note
- type ProtoFile
- type ProtoImport
- type ProtoOption
- type Result
Constants ¶
const Module = "github.com/aidarbn/platform-go"
Module is the Go module of the platform.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Change ¶
type Change struct {
Path string // relative to the project root
Codemods []string // names of the codemods that changed it
Content []byte
}
Change is a file a run rewrote.
type Codemod ¶
type Codemod struct {
Version string // the platform version that brings the change
Name string
Description string
// Covers are the incompatible changes of kit the codemod answers for, as apidiff names
// them relative to the module: "kit/adminx.(*Auth).Login". scripts/apicheck.sh accepts
// an incompatible change covered here or in the manual steps of docs/upgrades.md.
Covers []string
Fix func(f *File) // rewrites one Go file through File.Replace; runs while pending
Check func(f *File) // reports code that cannot compile with Version; runs every time
Proto func(f *ProtoFile) // rewrites one .proto file; runs while pending
}
Codemod is one rewrite.
func AdminxNoTOTP ¶ added in v0.9.0
func AdminxNoTOTP() Codemod
AdminxNoTOTP follows v0.6.0, where the admin panel signs in with a password only: CreateUser loses the twoFactor argument and the secret result, Login loses the code argument. References to the removed TOTP names and fields go to a person.
func All ¶
func All() []Codemod
All are the codemods of the platform, oldest first. Add one with the change of kit that needs it, under the version that will be released with it:
RenameSymbol("v0.3.0", "github.com/aidarbn/platform-go/kit/modules/riverx", "NewQueue", "Queue"),
An incompatible change no codemod can follow is described under its version in the manual steps of docs/upgrades.md instead; scripts/apicheck.sh wants one of the two.
func Pending ¶
Pending returns the codemods newer than the version the project was applied with, in version order. An empty or invalid version means before codemods existed: all of them.
func RenameSymbol ¶
RenameSymbol is the common codemod: an exported name of a kit package changes.
type File ¶
type File struct {
Path string
Fset *token.FileSet
AST *ast.File
// contains filtered or unexported fields
}
File is a Go file a codemod rewrites. Edits replace source ranges, so comments and layout outside them stay as the developer wrote them.
func (*File) ImportName ¶
ImportName returns the name a package is known by in the file, when it is imported.
func (*File) PackageImports ¶ added in v0.9.0
PackageImports reports whether any file of the package of the file imports a path: values of a kit type can be used in a file that does not import kit itself.
func (*File) PackageRef ¶ added in v0.9.0
PackageRef reports whether an expression is name.sel for a package imported under name and not shadowed in the file.
func (*File) ReplaceRange ¶ added in v0.9.0
ReplaceRange replaces the source between two positions; an empty text deletes it.
type Note ¶ added in v0.9.0
type Note struct {
Path string // relative to the project root
Line int
Codemod string
Message string
}
Note is a place a person has to change: what a codemod could not rewrite.
type ProtoFile ¶ added in v0.9.0
type ProtoFile struct {
Path string
// contains filtered or unexported fields
}
ProtoFile is a .proto file a codemod rewrites. There is no syntax tree: a codemod finds imports and options through the helpers, which skip comments and strings, and replaces byte ranges, so everything else stays as the developer wrote it.
func (*ProtoFile) Imports ¶ added in v0.9.0
func (f *ProtoFile) Imports() []ProtoImport
Imports lists the import statements.
func (*ProtoFile) Options ¶ added in v0.9.0
func (f *ProtoFile) Options(name string) []ProtoOption
Options lists the custom options whose name, inside the parentheses, is name or starts with name followed by a dot.
func (*ProtoFile) Replace ¶ added in v0.9.0
Replace replaces the source between two offsets; an empty text deletes it.
type ProtoImport ¶ added in v0.9.0
type ProtoImport struct {
Path string
Start, End int // the statement, from import to the semicolon
}
ProtoImport is an import statement: import "path";
type ProtoOption ¶ added in v0.9.0
type ProtoOption struct {
Name string // inside the parentheses, without a leading dot: gnostic.openapi.v3.operation
Field bool // a field or enum value option inside brackets
Start, End int // a statement from option to the semicolon; a field option from ( to the value
ValueStart int // the value: a scalar or a {} aggregate
ValueEnd int
}
ProtoOption is a custom option: a statement option (name).field = value; or a field option [(name) = value].