resolve

type Graph ¶

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

Graph models import dependencies among UB files. Nodes are opaque string IDs assigned by the caller - typically a canonical filesystem path for local sources or `url@commit/subdir` for remote ones. Edges point from a file to each file it imports.

func NewGraph() *Graph

func ResolveAll(id string, f *lang.File, resolver Resolver) (*Graph, []error)

func (g *Graph) AddEdge(from, to string)

func (g *Graph) AddNode(id string)

func (g *Graph) DetectCycles() [][]string

type ImportRef ¶

type ImportRef interface {
	// contains filtered or unexported methods
}

ImportRef is a parsed value from an `imports:` block.

func ParseImportRef(raw string) (ImportRef, error)

type LocalImport ¶

type LocalImport struct {
	Path string
}

LocalImport names a sibling on the operator's filesystem. Local imports do not have pinned versions; their content is whatever the developer has at the path now. Compile from a clean checkout to make the result reproducible.

type LocalResolver ¶

type LocalResolver struct {
	Root string
}

LocalResolver resolves *LocalImport refs against a working directory root. Relative paths in the import are joined to Root.

func NewLocalResolver(root string) *LocalResolver

func (r *LocalResolver) Resolve(ref ImportRef) (*Source, error)

type LockEntry ¶

type LockEntry struct {
	Kind           LockKind `json:"kind"`
	URL            string   `json:"url"`
	Subdir         string   `json:"subdir,omitempty"`
	Constraint     string   `json:"constraint"`
	ResolvedCommit string   `json:"resolved-commit"`
	SubdirHash     string   `json:"subdir-hash"`
}

LockEntry records one resolved import.

type LockFile ¶

type LockFile struct {
	Version int                   `json:"version"`
	Imports map[string]*LockEntry `json:"imports"`
}

LockFile is the on-disk schema for `unobin.lock`. Pins each import's resolved git commit and a content hash of the relevant subdirectory so compiles are reproducible across machines.

func DecodeLockFile(b []byte) (*LockFile, error)

func NewLockFile() *LockFile

func ReadLockFile(path string) (*LockFile, error)

type LockKind ¶

type LockKind string

LockKind records whether an imported library is Go- or UB-implemented in the lock.

const (
	LockKindGoLibrary LockKind = "go-library"
	LockKindUBLibrary LockKind = "ub-library"
)

type RemoteImport ¶

type RemoteImport struct {
	URL     string
	Subdir  string
	Version string
}

RemoteImport names an importable repo by host + owner/name, optional subdir within the repo, and a version constraint. Constraint format is not parsed here (semver tags, branch names, etc. all flow through as strings) and the resolver enforces what's allowed.

type RemoteResolver ¶

type RemoteResolver struct {
	CacheRoot string
}

RemoteResolver resolves *RemoteImport refs by fetching the named git repo at the requested constraint, caching the working tree under CacheRoot, and exposing the requested subdir as a Source.

CacheRoot is the directory holding `imports/<host>/<path>/<commit>/`. `NewRemoteResolver` defaults it to `<user-cache-dir>/unobin`.

func NewRemoteResolver() (*RemoteResolver, error)

func (r *RemoteResolver) Resolve(ref ImportRef) (*Source, error)

type Resolution ¶

type Resolution struct {
	Kind         ResolutionKind
	LocalAlias   string
	Ref          ImportRef
	Path         string
	Version      string
	CanonicalKey string
	SourcePath   string
}

Resolution describes one import after the walker reaches it. For Go imports, Path is the canonical Go-import path (URL plus subdir when present) and Version is the pinned version. For UB imports, CanonicalKey is the dedup key (see UBKey) and visitors look up their per-library state by that key. SourcePath is the on-disk directory where the resolver fetched the import, useful for compile-time inspection.

func WalkUB(
	refs map[string]ImportRef, resolver Resolver, v UBVisitor,
) ([]Resolution, error)

type ResolutionKind ¶

type ResolutionKind int

ResolutionKind tags how an import was resolved.

const (
	// ResolutionGo names a Go-library import: a remote ref whose resolved
	// source has no kind-prefixed body files at its root.
	ResolutionGo ResolutionKind = iota + 1
	// ResolutionUB names a UB-library import: a ref whose resolved source
	// has kind-prefixed body files at its root.
	ResolutionUB
)

type ResolvedImport ¶

type ResolvedImport struct {
	Ref    ImportRef
	Source *Source
}

ResolvedImport pairs a parsed ImportRef with the Source the resolver returned for it. Source is nil when the resolver errored on this alias. The corresponding error is in the returned slice.

type Resolver ¶

type Resolver interface {
	Resolve(ref ImportRef) (*Source, error)
}

Resolver turns an ImportRef into a Source. Implementations cover one kind of import each (local filesystem, remote git, etc.); callers dispatch by type-switching on the ref.

type Source ¶

type Source struct {
	FS     fs.FS
	Path   string
	Commit string
	Hash   string
}

Source is the file tree of a resolved import, rooted at the import's subdirectory, or the repo root when there is no subdir. For remote imports, Commit and Hash record the resolved git commit and a content hash so the lock file can pin reproducibility. Local imports leave both empty since their content is whatever the developer has now. Path is the on-disk directory the source was fetched into, which the dev CLI uses for compile-time inspection of Go-library source.

type UBLibrary ¶

type UBLibrary struct {
	Bodies      map[string]*lang.File
	Kinds       map[string]string
	BodyImports map[string][]Resolution
}

UBLibrary has everything the visitor needs about a UB library the first time the walker reaches it. Bodies maps composite type name to the parsed body file; the type name comes from a kind-prefixed filename (`<kind>-<type>.ub`). Kinds maps the same type name to its kind (`resource`, `data`, or `action`). BodyImports maps the type name to the resolved imports declared by that body, in alias-sorted order so callers see a stable view across runs.

type UBVisitor ¶

type UBVisitor interface {
	// OnGoImport is called for every site whose import resolves to a
	// Go library. May fire multiple times with the same path when the
	// same library is imported from several sites; visitors that need
	// uniqueness dedup themselves.
	OnGoImport(alias, path, version string) error
	// OnUBLibrary is called once per canonical key. alias is the local
	// alias of whichever site first reached the library (which matters
	// when the visitor names a directory or package after it).
	OnUBLibrary(alias, canonicalKey string, ref ImportRef, lib *UBLibrary) error
}

UBVisitor is implemented by callers that want to consume the walked import graph. The walker invokes its methods as it descends.