onek

package
v0.35.0 Latest Latest
Warning

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

Go to latest
Published: Oct 16, 2026 License: MIT Imports: 49 Imported by: 0

Documentation

Index

Constants

View Source
const (
	DefaultReleaseBase = "https://github.com/1homsi/onekit/releases/download"
)

Variables

This section is empty.

Functions

func Build

func Build(dir string) error

Build parses and compiles every .onk file under dir, then generates every target configured in onekit.toml.

func Check

func Check(dir string) error

Check validates the project configuration and every schema under the project's schema tree (see Config.SchemaRoot) without generating output.

func Compatibility

func Compatibility(previousDir, currentDir string) ([]onkcompat.Finding, error)

Compatibility compares two schema directories and returns breaking changes.

func CompatibilityAgainstRef added in v0.19.0

func CompatibilityAgainstRef(ref, currentDir string) ([]onkcompat.Finding, error)

func DecoratorCompletions added in v0.18.0

func DecoratorCompletions(prefix string) []map[string]any

func Format

func Format(dir string, check bool) error

Format formats every .onk file under dir. In check mode it never writes and returns a FormatError when any file differs from the canonical form.

func FormatFiles added in v0.19.0

func FormatFiles(paths []string, check bool) error

func Init

func Init(dir string, force bool) error

Init creates a small, immediately buildable OneKit project.

func InitTemplateProject added in v0.21.0

func InitTemplateProject(dir string, force bool, template string) error

func NewLanguageMCPServer

func NewLanguageMCPServer(dir, version string) (*mcp.Server, error)

NewLanguageMCPServer exposes read-only compiler-backed queries over MCP.

func NormalizeVersion added in v0.26.0

func NormalizeVersion(version string) string

NormalizeVersion trims a leading "v" so "v0.25.5" and "0.25.5" compare equal.

func PinnedVersion added in v0.26.0

func PinnedVersion(dir string) (string, error)

PinnedVersion returns the release a project pins with `version = "x.y.z"` in its onekit.toml, or "" when there is no config or no pin. It reads only that key, so it works for projects whose other settings a different release added.

func RunLSP

func RunLSP(in io.Reader, out io.Writer, dir string) error

RunLSP serves one workspace over stdio, with full-document synchronization. An explicit dir overrides the client's root URI (useful for monorepos).

func RunMockWithReload added in v0.19.0

func RunMockWithReload(ctx context.Context, dir string, opts MockOptions, interval time.Duration, out io.Writer) error

RunMockWithReload serves the mock like MockServer.Run and rebuilds it whenever the project's schema or config changes.

func VerifyGenerated added in v0.19.0

func VerifyGenerated(dir string) error

func Watch

func Watch(ctx context.Context, dir string, interval time.Duration, out io.Writer) error

Watch performs an initial build and rebuilds after schema/config changes. Build failures are reported and do not terminate the watch, allowing an editor to keep working while a file is temporarily incomplete.

Types

type BuildSummary added in v0.19.0

type BuildSummary struct {
	Targets []string
	Files   int
	Cached  bool
}

func BuildWithSummary added in v0.19.0

func BuildWithSummary(dir string) (BuildSummary, error)

type Config

type Config struct {
	// Version pins the onek release this project builds with. When it differs
	// from the running binary, onek downloads that release (checksum
	// verified), caches it and hands the command over to it.
	Version          string   `toml:"version"`
	RepeatedStyle    string   `toml:"repeated_style"`
	SchemaExtensions []string `toml:"schema_extensions"`
	Module           string   `toml:"module"`
	// SchemaRoot points at the directory holding the .onk schema tree,
	// relative to the project directory (the one containing onekit.toml).
	// It lets repositories keep schemas in a subdirectory while generator
	// outputs stay anchored elsewhere. Defaults to "." - i.e. the schema
	// tree and the project directory are the same. Base-path inference and
	// cross-package import mirroring are computed relative to this root;
	// output containment keeps being validated against the project dir.
	SchemaRoot           string         `toml:"schema_root"`
	RoutePrefix          string         `toml:"route_prefix"`
	AllowLegacyContracts bool           `toml:"allow_legacy_contracts"`
	Int64Encoding        string         `toml:"int64_encoding"`
	EmitZeroValues       bool           `toml:"emit_zero_values"`
	Generate             GenerateConfig `toml:"generate"`
	// contains filtered or unexported fields
}

func LoadConfig

func LoadConfig(dir string) (*Config, error)

func (*Config) CompileOptions added in v0.25.0

func (c *Config) CompileOptions() onkcompile.CompileOptions

CompileOptions is the single place the project's compile-affecting settings become compiler options, so every command (build, check, mock, compat, language server) compiles a project the same way.

func (*Config) EnabledTargets added in v0.19.0

func (c *Config) EnabledTargets() []string

func (*Config) ProjectDir

func (c *Config) ProjectDir() string

ProjectDir returns the absolute canonical directory containing onekit.toml. Generator outputs and the drift manifest anchor here.

func (*Config) SchemaDir

func (c *Config) SchemaDir() string

SchemaDir returns the absolute canonical root of the .onk schema tree. It defaults to ProjectDir when schema_root is not configured.

type ConfigError

type ConfigError struct {
	Path   string
	Line   int
	Column int
	Err    error
}

ConfigError gives editor integrations a concrete file location for TOML and project configuration failures while preserving the wrapped cause.

func (*ConfigError) Error

func (e *ConfigError) Error() string

func (*ConfigError) Unwrap

func (e *ConfigError) Unwrap() error

type Diagnostic

type Diagnostic struct {
	Path    string `json:"path,omitempty"`
	Line    int    `json:"line,omitempty"`
	Column  int    `json:"column,omitempty"`
	Code    string `json:"code,omitempty"`
	Message string `json:"message"`
}

Diagnostic is the stable machine-readable shape used by `onek check --json`. Paths are kept absolute when the caller supplied an absolute path and otherwise remain relative to preserve useful project-local output.

func Diagnostics

func Diagnostics(err error) []Diagnostic

Diagnostics converts one error chain into the JSON diagnostics consumed by editors and CI. It intentionally returns one fallback diagnostic for configuration and filesystem errors that do not have source locations.

type DriftError added in v0.19.0

type DriftError struct {
	Files []string
}

func (*DriftError) Error added in v0.19.0

func (e *DriftError) Error() string

func (*DriftError) ExitCode added in v0.19.0

func (e *DriftError) ExitCode() int

type FormatError

type FormatError struct {
	Files []string
}

FormatError reports the files that would change when formatting in check mode. It is intentionally machine-readable for editor and CI integrations.

func (*FormatError) Error

func (e *FormatError) Error() string

type GenerateConfig

type GenerateConfig struct {
	GoServer     *GoServerTargetConfig `toml:"go-server"`
	GoClient     *TargetConfig         `toml:"go-client"`
	TSClient     *TSClientTargetConfig `toml:"ts-client"`
	TSServer     *TSServerTargetConfig `toml:"ts-server"`
	PythonClient *TargetConfig         `toml:"python-client"`
	DartClient   *TargetConfig         `toml:"dart-client"`
	SwiftClient  *TargetConfig         `toml:"swift-client"`
	RustClient   *TargetConfig         `toml:"rust-client"`
	RustServer   *TargetConfig         `toml:"rust-server"`
	OpenAPI      *OpenAPITargetConfig  `toml:"openapi"`
}

type GoServerTargetConfig added in v0.25.2

type GoServerTargetConfig struct {
	Out string `toml:"out"`
	// Runtime is "package" (the default: every generated package carries its
	// own server core) or "shared" (one runtime package holds it, so the
	// error writer, authorizer, middleware and options are the same types in
	// every package).
	Runtime string `toml:"runtime"`
	// RuntimeDir is where the shared runtime package is written, relative to
	// Out. It defaults to "onekitrt".
	RuntimeDir string `toml:"runtime_dir"`
	// JSONContentType is the Content-Type of JSON responses the server
	// writes, for example "application/json; charset=utf-8". It defaults to
	// "application/json".
	JSONContentType string `toml:"json_content_type"`
	ServiceFilter
}

type InitTemplate added in v0.21.0

type InitTemplate struct {
	Name        string
	Description string
	// contains filtered or unexported fields
}

func InitTemplates added in v0.21.0

func InitTemplates() []InitTemplate

type LanguageFile

type LanguageFile struct {
	Path    string   `json:"path"`
	Package string   `json:"package"`
	Imports []string `json:"imports"`
}

type LanguageSnapshot

type LanguageSnapshot struct {
	Root        string            `json:"root"`
	Files       []LanguageFile    `json:"files"`
	Symbols     []*LanguageSymbol `json:"symbols"`
	Diagnostics []Diagnostic      `json:"diagnostics"`
	// contains filtered or unexported fields
}

LanguageSnapshot is rebuilt from disk (plus editor overlays) for each request. References are emitted only after successful compilation, never guessed by name.

func AnalyzeLanguage

func AnalyzeLanguage(dir string, overlays map[string]string) (*LanguageSnapshot, error)

func (*LanguageSnapshot) References

func (s *LanguageSnapshot) References(symbol *LanguageSymbol, includeDeclaration bool) []Location

func (*LanguageSnapshot) Search

func (s *LanguageSnapshot) Search(query, path string) []*LanguageSymbol

func (*LanguageSnapshot) SymbolAt

func (s *LanguageSnapshot) SymbolAt(path string, p Position) *LanguageSymbol

type LanguageSymbol

type LanguageSymbol struct {
	Name          string   `json:"name"`
	QualifiedName string   `json:"qualifiedName"`
	Kind          string   `json:"kind"`
	Detail        string   `json:"detail"`
	Documentation string   `json:"documentation,omitempty"`
	Location      Location `json:"location"`
}

type Location

type Location struct {
	Path  string `json:"path"`
	Range Range  `json:"range"`
}

type MockOptions

type MockOptions struct {
	// Addr is the listen address; defaults to 127.0.0.1:8080 when empty.
	Addr string
	// Seed makes error injection and latency jitter deterministic.
	Seed int64
	// ErrorRate in [0,1] serves declared typed errors instead of success
	// responses with the configured probability.
	ErrorRate float64
	// Latency injects up to this much random delay before responding.
	Latency time.Duration
	NoCORS  bool
}

MockOptions configures the generated dev server.

type MockServer

type MockServer struct {
	// contains filtered or unexported fields
}

MockServer serves schema-derived fixtures for every compiled route. Fixtures are pure functions of the schema - identical inputs always produce byte-identical bodies - while rng drives only latency jitter and error-injection draws.

func NewMockServer

func NewMockServer(dir string, opts MockOptions) (*MockServer, error)

NewMockServer parses and compiles the project at dir (honoring schema_root/route_prefix) and returns a ready-to-serve mock.

func (*MockServer) Handler

func (m *MockServer) Handler() http.Handler

func (*MockServer) Routes

func (m *MockServer) Routes() int

Routes reports how many RPCs were registered.

func (*MockServer) Run

func (m *MockServer) Run(ctx context.Context, addr string, out io.Writer) error

Run serves until ctx is cancelled or the listener fails.

type OpenAPITargetConfig

type OpenAPITargetConfig struct {
	ServiceFilter
	Out         string   `toml:"out"`
	Title       string   `toml:"title"`
	Version     string   `toml:"version"`
	Description string   `toml:"description"`
	Servers     []string `toml:"servers"`
}

type ParseDiagnosticError

type ParseDiagnosticError struct {
	Path string
	Err  error
}

ParseDiagnosticError attaches the source path to a parser/lexer error while retaining the original error for errors.As and normal error wrapping.

func (*ParseDiagnosticError) Error

func (e *ParseDiagnosticError) Error() string

func (*ParseDiagnosticError) Unwrap

func (e *ParseDiagnosticError) Unwrap() error

type Position

type Position struct {
	Line      int `json:"line"`
	Character int `json:"character"`
}

Position and Range use the LSP convention: zero-based lines and UTF-16 columns.

type Range

type Range struct {
	Start Position `json:"start"`
	End   Position `json:"end"`
}

type ReleaseSource added in v0.26.0

type ReleaseSource struct {
	BaseURL  string
	CacheDir string
	GOOS     string
	GOARCH   string
	Client   *http.Client
}

ReleaseSource describes where release archives come from and where the verified binaries are cached.

func (ReleaseSource) Fetch added in v0.26.0

func (s ReleaseSource) Fetch(ctx context.Context, version string) (string, error)

Fetch returns the path of the verified onek binary for version, downloading and caching it when needed. The archive's SHA-256 must match the release's checksums.txt.

type ServiceFilter added in v0.25.2

type ServiceFilter struct {
	IncludeServices []string `toml:"include_services"`
	ExcludeServices []string `toml:"exclude_services"`
	IncludePackages []string `toml:"include_packages"`
	ExcludePackages []string `toml:"exclude_packages"`
}

ServiceFilter narrows the services a generator target produces code for. Patterns are shell-style globs over the service name (Orders, Admin*). With include_services set, only matching services are generated; any service matching exclude_services is then dropped. Types are always generated in full unless include_packages / exclude_packages narrow the schema directories (packages) the target emits at all.

type TSClientTargetConfig

type TSClientTargetConfig struct {
	Out string `toml:"out"`
	MSW bool   `toml:"msw"`
	// Runtime is "package" (the default: every client module declares its own
	// ApiError and helpers) or "shared" (one runtime module holds them, so
	// ApiError is a single class across every package's client).
	Runtime string `toml:"runtime"`
	// RuntimeDir is where the shared runtime module is written, relative to
	// Out. It defaults to "onekitrt".
	RuntimeDir string `toml:"runtime_dir"`
	ServiceFilter
	// FieldNames is "camel" (the default: isDefault) or "wire" (is_default,
	// the name the field has on the wire).
	FieldNames string `toml:"field_names"`
}

type TSServerTargetConfig added in v0.25.2

type TSServerTargetConfig struct {
	Out        string `toml:"out"`
	FieldNames string `toml:"field_names"`
	ServiceFilter
}

type TargetConfig

type TargetConfig struct {
	Out string `toml:"out"`
	ServiceFilter
}

Jump to

Keyboard shortcuts

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