project

Documentation

Overview

Package project provides project-aware operations: root discovery, ginger.yaml loading, and automatic structure detection for existing Go projects.

Index

• Variables
• func FindRoot(startDir string) (string, error)
• func Validate(root string, gy *GingerYAML) error
• type GingerYAML
  • func DefaultGingerYAML(projectType string) *GingerYAML
• type Inspection
  • func Inspect(p *Project) (*Inspection, error)
• type PathStatus
• type Project
  • func Detect(root string) (*Project, error)
  • func Load(root string) (*Project, error)
  • func (p *Project) BaseDir() (string, error)
  • func (p *Project) GoVersion() string
  • func (p *Project) HasGingerYAML() bool
  • func (p *Project) ProjectType() string
  • func (p *Project) ResolvePath(key string) (string, error)
  • func (p *Project) ResolveRelative(path string) (string, error)
  • func (p *Project) ShouldOverwrite() bool
• type ProjectConfig
• type Route
• type RulesConfig
• type StructureConfig

Variables

var ErrNoProject = errors.New("no project root found")

ErrNoProject is returned when no project root can be found.

Functions

func FindRoot

func FindRoot(startDir string) (string, error)

FindRoot walks up from startDir looking for project markers in priority order: 1. ginger.yaml, 2. go.mod, 3. .git.

func Validate

func Validate(root string, gy *GingerYAML) error

Validate verifies that the contract cannot address files outside the discovered project root and that declared values are supported.

Types

type GingerYAML

type GingerYAML struct {
	Project   ProjectConfig   `yaml:"project"`
	Structure StructureConfig `yaml:"structure"`
	Rules     RulesConfig     `yaml:"rules"`
}

GingerYAML represents the ginger.yaml contract file.

func DefaultGingerYAML

func DefaultGingerYAML(projectType string) *GingerYAML

DefaultGingerYAML returns a default ginger.yaml for autodetected projects.

type Inspection

type Inspection struct {
	Root       string                `json:"root"`
	Module     string                `json:"module,omitempty"`
	Type       string                `json:"type"`
	GoVersion  string                `json:"go_version,omitempty"`
	GingerYAML bool                  `json:"ginger_yaml"`
	Structure  map[string]PathStatus `json:"structure"`
	Routes     []Route               `json:"routes,omitempty"`
	Features   []string              `json:"features,omitempty"`
	Datastores []string              `json:"datastores,omitempty"`
	TestFiles  int                   `json:"test_files"`
	Warnings   []string              `json:"warnings,omitempty"`
}

Inspection is the stable, serializable project analysis model.

func Inspect

func Inspect(p *Project) (*Inspection, error)

Inspect analyzes files without executing project code.

type PathStatus

type PathStatus struct {
	Path   string `json:"path"`
	Exists bool   `json:"exists"`
	Files  int    `json:"files,omitempty"`
}

PathStatus describes one configured structural location.

type Project

type Project struct {
	Root     string
	YAML     *GingerYAML
	Module   string
	IsGinger bool
}

Project holds the resolved project context.

func Detect

func Detect(root string) (*Project, error)

Detect builds a project context from the existing filesystem without reading ginger.yaml. It is used by ginger init and never moves files.

func Load

func Load(root string) (*Project, error)

Load loads the project context from the given root directory. If ginger.yaml exists, it is loaded and validated. If it does not exist, the project structure is auto-detected and a default config is returned.

func (*Project) BaseDir

func (p *Project) BaseDir() (string, error)

BaseDir returns the directory used as the base for structure paths.

func (*Project) GoVersion

func (p *Project) GoVersion() string

GoVersion returns the version declared by the project's go.mod.

func (*Project) HasGingerYAML

func (p *Project) HasGingerYAML() bool

HasGingerYAML returns true if ginger.yaml exists at the project root.

func (*Project) ProjectType

func (p *Project) ProjectType() string

ProjectType returns the detected project type.

func (*Project) ResolvePath

func (p *Project) ResolvePath(key string) (string, error)

ResolvePath resolves a logical structure key inside the project root.

func (*Project) ResolveRelative

func (p *Project) ResolveRelative(path string) (string, error)

ResolveRelative resolves a project-relative path after validating containment.

func (*Project) ShouldOverwrite

func (p *Project) ShouldOverwrite() bool

ShouldOverwrite returns true if rules allow overwriting files.

type ProjectConfig

type ProjectConfig struct {
	Type string `yaml:"type"` // service, worker, cli, generic, library
	Root string `yaml:"root"`
}

ProjectConfig holds project-level metadata.

type Route

type Route struct {
	Method string `json:"method"`
	Path   string `json:"path"`
	File   string `json:"file"`
	Line   int    `json:"line"`
}

Route describes an explicitly annotated or recognizable HTTP route.

type RulesConfig

type RulesConfig struct {
	Overwrite              bool `yaml:"overwrite"`
	CreateMissingDirs      bool `yaml:"create_missing_dirs"`
	RequirePlanBeforeApply bool `yaml:"require_plan_before_apply"`
}

RulesConfig controls safe generation behavior.

type StructureConfig

type StructureConfig struct {
	Cmd          string `yaml:"cmd"`
	API          string `yaml:"api"`
	Handlers     string `yaml:"handlers"`
	Middlewares  string `yaml:"middlewares"`
	Models       string `yaml:"models"`
	Services     string `yaml:"services"`
	Repositories string `yaml:"repositories"`
	Ports        string `yaml:"ports"`
	Adapters     string `yaml:"adapters"`
	Config       string `yaml:"config"`
	Docs         string `yaml:"docs"`
	Tests        string `yaml:"tests"`
	Migrations   string `yaml:"migrations"`
}

StructureConfig maps logical names to directory paths.