codemod

package
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 27, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

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

View Source
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
	// Skip leaves the codemod out for a project it does not concern, by its settings.
	Skip func(p Project) bool
}

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 Applicable added in v0.10.0

func Applicable(mods []Codemod, p Project) []Codemod

Applicable leaves out the codemods that skip a project.

func GnosticOptions added in v0.10.0

func GnosticOptions() Codemod

GnosticOptions follows v0.10.0, where the platform's own OpenAPI generator is the default and reads its own options instead of gnostic annotations: a summary and a tag of an operation become (platform.openapi.v1.method), descriptions and titles become proto comments, examples become (platform.openapi.v1.field) and (platform.openapi.v1.message), deprecated an option of the method. The rest — the document option, formats, patterns, responses — goes to a person. Projects that keep the connect generator keep their annotations.

func Pending

func Pending(all []Codemod, applied string) []Codemod

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

func RenameSymbol(version, pkg, from, to string) Codemod

RenameSymbol is the common codemod: an exported name of a kit package changes.

type Declaration added in v0.10.0

type Declaration struct {
	Kind  string // field, or the keyword of a block: message, service, rpc, enum, oneof; file at the top level
	Name  string
	Start int // the first token of the declaration: the type of a field, the keyword of a block
}

Declaration is what an option belongs to.

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

func (f *File) ImportName(path string) (string, bool)

ImportName returns the name a package is known by in the file, when it is imported.

func (*File) PackageImports added in v0.9.0

func (f *File) PackageImports(path string) bool

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

func (f *File) PackageRef(e ast.Expr, pkg string) (*ast.SelectorExpr, bool)

PackageRef reports whether an expression is name.sel for a package imported under name and not shadowed in the file.

func (*File) Replace

func (f *File) Replace(n ast.Node, text string)

Replace replaces the source of a node.

func (*File) ReplaceRange added in v0.9.0

func (f *File) ReplaceRange(from, to token.Pos, text string)

ReplaceRange replaces the source between two positions; an empty text deletes it.

func (*File) Report added in v0.9.0

func (f *File) Report(n ast.Node, msg string)

Report leaves a note for a person at a node: what the codemod could not rewrite.

func (*File) Source

func (f *File) Source(n ast.Node) string

Source returns the source of a node.

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.

func (Note) String added in v0.9.0

func (n Note) String() string

type Project added in v0.10.0

type Project struct {
	OpenAPIGenerator string // the openapi.generator of the api module, empty without it
}

Project is what a codemod may ask about the settings of a project.

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 ParseProto added in v0.10.0

func ParseProto(path string, src []byte) *ProtoFile

ParseProto reads a .proto file for a rewrite outside of a codemod, such as the converter of openapiv2 options: the same option finder, the same edits.

func (*ProtoFile) BlockEnd added in v0.10.0

func (f *ProtoFile) BlockEnd(start int) int

BlockEnd is the offset after the } that closes the block whose declaration starts at an offset, or -1 without one.

func (*ProtoFile) CommentAbove added in v0.10.0

func (f *ProtoFile) CommentAbove(off int) string

CommentAbove is the // comment on the lines right above an offset, without the slashes and the space after them.

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) Owner added in v0.10.0

func (f *ProtoFile) Owner(o ProtoOption) Declaration

Owner returns the declaration of an option: the field a field option sits on, the block an option statement sits in, the file for one at the top level.

func (*ProtoFile) Replace added in v0.9.0

func (f *ProtoFile) Replace(start, end int, text string)

Replace replaces the source between two offsets; an empty text deletes it.

func (*ProtoFile) Report added in v0.9.0

func (f *ProtoFile) Report(offset int, msg string)

Report leaves a note for a person at an offset.

func (*ProtoFile) Result added in v0.10.0

func (f *ProtoFile) Result() ([]byte, error)

Result applies the edits made so far to the source.

func (*ProtoFile) Source added in v0.9.0

func (f *ProtoFile) Source() string

Source returns the whole file.

func (*ProtoFile) Text added in v0.9.0

func (f *ProtoFile) Text(start, end int) string

Text returns the source between two offsets.

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].

type Result added in v0.9.0

type Result struct {
	Changes []Change
	Notes   []Note
}

Result is what a run would do.

func Run

func Run(dir string, pending, checks []Codemod) (Result, error)

Run applies the pending codemods to the Go and proto files of the project without writing anything, then the checks of every codemod in checks to the result. It returns the files that change and the notes for a person.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL