Documentation
¶
Overview ¶
Package scaffold generates Climax application and command files. This file contains all AST-based analysis used to locate and modify the dispatcher file without relying solely on embedded text markers.
Package scaffold – drift.go detects and repairs structural drift between climax's own source files and the scaffold template files.
The AST-based approach parses the actual Go source with go/parser to make structural inferences (e.g. "does func main call signal.NotifyContext?") rather than fragile string matching. Template patching works by reading the relevant template file from pkg/scaffold/templates/, applying text replacements, and writing it back.
Package scaffold – lint.go detects structural drift between a user's climax-based application and the current scaffold templates, reporting each issue in unified-diff format so the caller can display actionable warnings.
Package scaffold generates Climax application and command files.
Index ¶
- Constants
- func AddCommand(dir, name, importPrefix string, opts AddOptions) (created, modified string, err error)
- func AddManCommand(dir, importPrefix string, opts ManOptions) (created, modified string, err error)
- func ApplyFixes(climaxDir string, items []DriftItem) error
- func InitApp(dir string, opts InitOptions) ([]string, error)
- func IsClimaxApp(dir string) error
- func NormalizeEnvPrefix(name string) string
- func ValidateCliName(name string) error
- func ValidateIdent(name string) error
- type AddOptions
- type DriftItem
- type InitOptions
- type LintIssue
- type ManOptions
Constants ¶
const ( ImportsMarker = "// climax:imports" CommandsMarker = "// register new commands here" )
Markers embedded in generated files so "climax add" can locate insertion points.
Variables ¶
This section is empty.
Functions ¶
func AddCommand ¶
func AddCommand( dir, name, importPrefix string, opts AddOptions, ) (created, modified string, err error)
AddCommand creates cmd/<name>/<name>.go and registers it in the dispatcher. It works whether or not the dispatcher file retains its text markers. It returns the relative paths of the created command file and the modified dispatcher file, both relative to dir.
func AddManCommand ¶
func AddManCommand( dir, importPrefix string, opts ManOptions, ) (created, modified string, err error)
AddManCommand creates cmd/man/man.go in the climax application rooted at dir and registers it in the dispatcher. importPrefix is the Go module import path for the application root.
It returns the relative paths of the created file and the modified dispatcher. After running AddManCommand, the caller must ensure the target application adds the required dependencies:
go get github.com/StevenACoffman/mango-ff github.com/muesli/roff
func ApplyFixes ¶
ApplyFixes patches the template files inside climaxDir for every DriftItem that has a patch attached. Items without patches (e.g. template-has-extra) are skipped. All patches targeting the same file are applied in a single read/write cycle. Returns an error if any patch fails.
func InitApp ¶
func InitApp(dir string, opts InitOptions) ([]string, error)
InitApp writes a complete Climax application scaffold to dir and returns the relative paths of every file it creates, in the order they were written.
func IsClimaxApp ¶
IsClimaxApp reports whether dir is the root of a Climax application. It accepts applications whether or not the text markers are present, using AST analysis as a fallback when markers have been removed.
func NormalizeEnvPrefix ¶ added in v0.5.0
NormalizeEnvPrefix derives a valid environment-variable prefix from name. It uppercases all ASCII letters, replaces hyphens and periods with underscores, and drops all other non-ASCII and non-alphanumeric characters.
Examples:
"myapp" → "MYAPP" "my-app" → "MY_APP" "my.app" → "MY_APP" "café" → "CAF" (non-ASCII é dropped)
func ValidateCliName ¶
ValidateCliName reports whether name is valid as a CLI command name. It allows letters, digits, hyphens, and underscores, starting with a letter or underscore.
func ValidateIdent ¶
ValidateIdent reports whether name is a valid Go identifier.
Types ¶
type AddOptions ¶
type AddOptions struct {
Name string // ff.Command.Name; defaults to the Go package name (positional arg)
Short string // ff.Command.ShortHelp; defaults to "<name> command"
Long string // ff.Command.LongHelp; defaults to "<Name> is a new command."
Parent string // Go package name of the parent command; defaults to the root package
}
AddOptions controls what AddCommand generates for the new command file.
type DriftItem ¶
type DriftItem struct {
Template string // "main", "cmd", "root", "version", or "man"
Property string // human-readable property name
InSource string // "present" or "absent"
InTemplate string // "present" or "absent"
// contains filtered or unexported fields
}
DriftItem describes a single structural difference between a climax source file and the corresponding scaffold template.
func DetectDrift ¶
DetectDrift analyses climaxDir (the root of the climax module) and returns the list of structural properties that are present in the real source but absent from the embedded templates, or vice-versa.
func (DriftItem) IsFixable ¶
IsFixable reports whether this drift item can be automatically repaired by ApplyFixes. It returns true only when the check defined a string-replacement patch — not all source-has/template-lacks items are auto-patchable (e.g. tabwriter output or GetVersionInfoFrom require a broader template rewrite).
type InitOptions ¶
type InitOptions struct {
ImportPrefix string // Go import path for the application root (required)
Name string // ff.Command.Name for the root; defaults to last segment of ImportPrefix
Short string // ff.Command.ShortHelp for the root; defaults to "TODO: describe <name> here"
Long string // ff.Command.LongHelp for the root; omitted if empty
RootPkg string // Go package name (and file basename) for the root config; defaults to "root"
EnvPrefix string // env var prefix for ff.WithEnvVarPrefix; defaults to NormalizeEnvPrefix(Name)
// NoEnvPrefix selects ff.WithEnvVars() (no prefix) over ff.WithEnvVarPrefix.
// When true, EnvPrefix is still normalized and used to rewrite the generated
// content, but the resulting file omits the prefix from both the Parse call
// and the climax:env-prefix marker. Mutually exclusive with a non-empty EnvPrefix
// at the CLI layer; both may be set here (EnvPrefix is ignored in the output).
NoEnvPrefix bool
NoVersion bool // when true, skip generating cmd/version/version.go
}
InitOptions controls what InitApp generates.
type LintIssue ¶
type LintIssue struct {
// File is the path relative to the application root, e.g. "main.go".
File string
// Property is a short human-readable name for the structural property.
Property string
// Diff is a unified-diff-style snippet showing found vs expected.
Diff string
}
LintIssue describes a single structural deviation found in a user's climax application, relative to the current scaffold templates.
type ManOptions ¶
type ManOptions struct {
// Section is the man page section number (1–8). Defaults to 1.
Section int
// Authors is baked into a WithSection("Authors", ...) call when non-empty.
Authors string
// Copyright is baked into a WithSection("Copyright", ...) call when non-empty.
Copyright string
}
ManOptions controls what AddManCommand generates for the man subcommand.
Source Files