pkgsplit

Overview ¶

Command pkgsplit is the in-module AST rewriter used to split a public package in place: the kept subset stays in the public directory, the remainder moves to an internal twin that imports the public package. It is a development tool only (never imported, never shipped).

Usage — a split is four mechanical passes plus compile-driven fixups:

# 1. list the exported package-level names a directory declares
go run ./internal/tools/pkgsplit decls -dir internal/encoding > /tmp/remainder.txt
go run ./internal/tools/pkgsplit decls -dir encoding -all > /tmp/kept.txt

# 2. qualify the moved files' references to names that stayed public
go run ./internal/tools/pkgsplit qualify -dir internal/encoding \
    -import github.com/frankbardon/pulse/encoding -names /tmp/kept.txt

# 3. turn method calls into package-function calls inside the twin
go run ./internal/tools/pkgsplit methods -dir internal/encoding \
    -methods BuildDecodePlan,ReadRecordAt

# 4. repoint every other file in the module at the twin
go run ./internal/tools/pkgsplit rewrite -root . \
    -from github.com/frankbardon/pulse/encoding \
    -to github.com/frankbardon/pulse/internal/encoding -alias encx \
    -names /tmp/remainder.txt -methods BuildDecodePlan,ReadRecordAt \
    -exclude internal/encoding

Declarations that must change sides inside a file that otherwise stays put move with `move` (doc comments travel with them; a new -dst file gets the -src import block, so run goimports on both afterwards):

go run ./internal/tools/pkgsplit move -src encoding/header.go \
    -dst internal/encoding/preamble.go -names ReadPreamble,Schema.Logical

The passes are purely syntactic (go/parser + go/format; no type checker, so the module needs no golang.org/x/tools dependency): a selector `<local>.Name` is rewritten only when <local> is the file's import name for -from and is not shadowed by a declaration in the file; a method call `x.M(args)` becomes `alias.M(x, args)` for every -methods name, so those names must be unique to the converted receiver types across the module. The compiler is the check — run `go build ./... && go vet ./...` after each pass.