compat

Documentation

Overview

internal/compat/builtins.go

internal/compat/detect.go

internal/compat/firstrun.go

internal/compat/import.go

internal/compat/prompt.go

internal/compat/report.go

Index

• func CheckFirstRun() (bool, error)
• func CheckSourceChanged(statePath string) (bool, error)
• func DefaultStatePath() string
• func FormatChangeNotice(rcFile string, skipped int) string
• func FormatHashrcComment(rcFile string) string
• func FormatHashrcCommentFiles(files []string) string
• func FormatImportSummary(report *Report) string
• func FormatWelcomePrompt(shell, rcFile string) string
• func FormatWelcomePromptFiles(files ShellFiles) string
• func IsNoopBuiltin(cmd string) bool
• func NoopBuiltins() map[string]NoopBuiltinFunc
• func ShouldShowMigrationPrompt() (shouldShow bool, previousShell, rcFile string)
• type ImportedItem
• type ItemType
• type NoopBuiltinFunc
• type Report
  • func FilterWithCompat(path, shell string) (string, *Report, error)
  • func NewReport(sourceFile, sourceShell string) *Report
  • func SourceWithCompat(ctx context.Context, path, shell string, stdout io.Writer) (*Report, error)
  • func (r *Report) AddImported(itemType ItemType, name, value string)
  • func (r *Report) AddSkipped(line int, content, reason string)
• type ShellFiles
  • func DetectPreviousShellFiles() ShellFiles
  • func (sf ShellFiles) Files() []string
• type SkippedItem
• type State
  • func LoadState(path string) (*State, error)
  • func (s *State) Save(path string) error
• type Summary

Functions

func CheckFirstRun

func CheckFirstRun() (bool, error)

CheckFirstRun checks if this is the first run using default paths.

func CheckSourceChanged

func CheckSourceChanged(statePath string) (bool, error)

CheckSourceChanged checks if the source file has changed since last import.

func DefaultStatePath

func DefaultStatePath() string

DefaultStatePath returns the default path for migration state.

func FormatChangeNotice

func FormatChangeNotice(rcFile string, skipped int) string

FormatChangeNotice returns a one-line notice about source file changes.

func FormatHashrcComment

func FormatHashrcComment(rcFile string) string

FormatHashrcComment returns the comment block for .hashrc.

func FormatHashrcCommentFiles

func FormatHashrcCommentFiles(files []string) string

FormatHashrcCommentFiles returns the comment block for .hashrc with multiple source files. Note: We don't include source commands here because mvdan/sh's internal source builtin parses with POSIX mode. Instead, Hash sources migration files directly at startup using SourceWithCompat which uses LangBash parsing.

func FormatImportSummary

func FormatImportSummary(report *Report) string

FormatImportSummary returns a formatted summary of the migration.

func FormatWelcomePrompt

func FormatWelcomePrompt(shell, rcFile string) string

FormatWelcomePrompt returns the welcome message for first-run migration.

func FormatWelcomePromptFiles

func FormatWelcomePromptFiles(files ShellFiles) string

FormatWelcomePromptFiles returns the welcome message showing all detected config files.

func IsNoopBuiltin

func IsNoopBuiltin(cmd string) bool

IsNoopBuiltin checks if a command is a no-op builtin.

func NoopBuiltins

func NoopBuiltins() map[string]NoopBuiltinFunc

NoopBuiltins returns a map of zsh-specific commands that should be no-ops.

func ShouldShowMigrationPrompt

func ShouldShowMigrationPrompt() (shouldShow bool, previousShell, rcFile string)

ShouldShowMigrationPrompt checks if we should show the migration prompt. Returns: shouldShow, previousShell, rcFile

Types

type ImportedItem

type ImportedItem struct {
	Type  ItemType `json:"type"`
	Name  string   `json:"name"`
	Value string   `json:"value,omitempty"`
}

ImportedItem represents a successfully imported item.

type ItemType

type ItemType string

ItemType represents the type of imported item.

const (
	ItemAlias    ItemType = "alias"
	ItemExport   ItemType = "export"
	ItemFunction ItemType = "function"
)

type NoopBuiltinFunc

type NoopBuiltinFunc func(args []string, report *Report) error

NoopBuiltinFunc is a function that handles a no-op builtin. It receives the arguments and a report to log the skip.

type Report

type Report struct {
	SourceFile    string         `json:"source_file"`
	SourceShell   string         `json:"source_shell"`
	SourceMtime   time.Time      `json:"source_mtime"`
	ImportTime    time.Time      `json:"import_time"`
	Summary       Summary        `json:"summary"`
	ImportedItems []ImportedItem `json:"imported_items,omitempty"`
	SkippedItems  []SkippedItem  `json:"skipped_items,omitempty"`
}

Report tracks the results of a migration import.

func FilterWithCompat

func FilterWithCompat(path, shell string) (string, *Report, error)

FilterWithCompat pre-processes a shell config file for compatibility. It returns the filtered content (with zsh-specific commands commented out) and a report of what was processed. The caller should execute the content through their own executor/interpreter.

func NewReport

func NewReport(sourceFile, sourceShell string) *Report

NewReport creates a new migration report.

func SourceWithCompat

func SourceWithCompat(ctx context.Context, path, shell string, stdout io.Writer) (*Report, error)

SourceWithCompat sources a shell rc file with graceful error handling. It skips zsh-specific builtins and recovers from parse errors. Note: This creates its own interpreter runner, so aliases/functions won't persist to the caller's shell. Use FilterWithCompat + executor for that.

func (*Report) AddImported

func (r *Report) AddImported(itemType ItemType, name, value string)

AddImported records a successfully imported item.

func (*Report) AddSkipped

func (r *Report) AddSkipped(line int, content, reason string)

AddSkipped records a skipped line.

type ShellFiles

type ShellFiles struct {
	Shell       string
	EnvFile     string // Environment file sourced for all invocations (e.g., .zshenv)
	ProfileFile string // Login shell config (e.g., .zprofile, .bash_profile)
	RCFile      string // Interactive shell config (e.g., .zshrc, .bashrc)
}

ShellFiles contains the config files for a shell.

func DetectPreviousShellFiles

func DetectPreviousShellFiles() ShellFiles

DetectPreviousShellFiles detects the user's previous shell and all its config files.

func (ShellFiles) Files

func (sf ShellFiles) Files() []string

Files returns a slice of existing files in source order (env first, then profile, then rc).

type SkippedItem

type SkippedItem struct {
	Line    int    `json:"line"`
	Content string `json:"content"`
	Reason  string `json:"reason"`
}

SkippedItem represents a line that was skipped during import.

type State

type State struct {
	SourceFile  string    `json:"source_file"`
	SourceFiles []string  `json:"source_files,omitempty"` // Individual file paths for sourcing
	SourceShell string    `json:"source_shell"`
	SourceMtime time.Time `json:"source_mtime"`
	LastImport  time.Time `json:"last_import"`
	Declined    bool      `json:"declined"`
	Summary     Summary   `json:"summary"`
}

State represents the persisted migration state.

func LoadState

func LoadState(path string) (*State, error)

LoadState reads the state from a JSON file.

func (*State) Save

func (s *State) Save(path string) error

Save writes the state to a JSON file.

type Summary

type Summary struct {
	Aliases   int `json:"aliases"`
	Exports   int `json:"exports"`
	Functions int `json:"functions"`
	Skipped   int `json:"skipped"`
}

Summary contains counts of imported/skipped items.