package resolve¶
Package resolve handles import resolution.
Resolves import paths (bare URLs, with // subdirs, local ./ paths) to concrete sources. Detects whether each import is a UB library (it has UB files at the root) or a Go library. Detects cycles at resolve time and reports them as compile errors. Enforces same-repo imports sharing a version.
Variables¶
ErrEmptyImportRef is returned when the source string is empty.
Functions¶
func CheckRemotePackageBoundary¶
CheckRemotePackageBoundary reports when a remote package is inside a nested project outside its selected owner.
func ContainsFactorySource¶
ContainsFactorySource reports whether s has a root file that declares a runnable factory instead of an importable library.
func ExtractSyntaxBodyImports¶
ExtractSyntaxBodyImports parses the imports declared by a typed factory body.
func GitRef¶
GitRef returns the first git ref used to fetch ref.
func HasCompositeExports¶
HasCompositeExports reports whether s has source-declared composite exports.
func IsGoLibrary¶
IsGoLibrary reports whether s looks like a Go library package or module.
func IsUBLibrary¶
IsUBLibrary reports whether s is a UB-implemented library: a directory with at least one source-declared composite export and no factory source. Project and project-lock files do not make a package importable by themselves. A malformed non-metadata `.ub` file is treated as a UB library candidate so the library parser can return the source diagnostic.
func LocalGoImportError¶
LocalGoImportError explains why a local import did not resolve to a UB library. When the local source is a Go module (it has a go.mod), a path import cannot work -- a Go library becomes a go.mod require, which needs a module path -- so the error shows how to import it by module path and replace it with the local path, naming the file each entry belongs in.
func SplitRepoSubdir¶
SplitRepoSubdir separates a repo URL from its optional subdir at the `//` separator. Without `//`, the whole input is the URL and there is no subdir.
func UBKey¶
UBKey is the dedup key for a UB-library import. Remote imports key on URL, subdir, and version; the `//\
func ValidateGoModulePath¶
ValidateGoModulePath checks a discovered Go module path against a remote import version.
func ValidateSyntaxCompositeBody¶
ValidateSyntaxCompositeBody checks a typed composite body against the requirements for its declared kind.
func WithDefaultScheme¶
WithDefaultScheme prepends `https://` to a bare URL like `github.com/owner/repo` so go-git knows to fetch it over HTTPS. URLs that already include a scheme (`https://`, `http://`, `ssh://`, `file://`, ...) or look like SCP-style ssh (`user@host:path`) or look like a filesystem path are left alone.
Types¶
type CompositeEntry¶
type CompositeEntry struct {
Kind string
Name string
SyntaxBody syntax.FactoryBody
SourceFile syntax.SourceFileSpec
}
type ContextResolver¶
ContextResolver resolves an import from the package source that declared it.
type ImportRef¶
ImportRef is a parsed value from an `imports:` block.
func ParseImportRef¶
ParseImportRef parses a string from an `imports:` block. Local imports start with `.` or `/`; remote imports name a repo URL and use the Terraform-style `//` separator to denote a subdirectory within the repo. Without `//` the whole string is the repo URL and the import has no subdir.
func ProjectLockVersion¶
ProjectLockVersion returns ref with a selected project-lock version when versions contains an owner for its remote project. Local imports and dependencies absent from the map are returned unchanged.
type LocalImport¶
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¶
LocalResolver resolves *LocalImport refs against a working directory root. Relative paths in the import are joined to Root.
func NewLocalResolver¶
NewLocalResolver returns a LocalResolver rooted at root. Pass the directory containing the factory or library files that own the imports.
func (*LocalResolver) Resolve¶
Resolve implements Resolver. The ref must be a *LocalImport; remote refs return an error so a misrouted call is reported clearly.
func (*LocalResolver) ResolveFrom¶
ResolveFrom resolves local refs relative to the package that declared them. Remote refs still return an error because LocalResolver handles only local filesystem paths.
type RemoteImport¶
type RemoteImport struct {
URL string
Subdir string
ProjectSubdir string
PackageSubdir string
Version string
}
RemoteImport names an importable repo by host + owner/name and an optional package subdir within the repo. The import string has no version; Version is filled in from project-lock.ub as the walk descends. ProjectSubdir and PackageSubdir are set after project or project-lock lookup when the owning project differs from the imported package.
type RemoteResolver¶
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/\
func NewRemoteResolver¶
NewRemoteResolver returns a RemoteResolver with CacheRoot set to UNOBIN_CACHE_ROOT when present, otherwise the user's cache directory joined with `unobin`.
func (*RemoteResolver) CachedSource¶
CachedSource returns source data for an existing cached commit without contacting git.
func (*RemoteResolver) CleanImports¶
CleanImports removes the cached import sources and returns the directory that was removed. It is a no-op when nothing is cached.
func (*RemoteResolver) ImportsDir¶
ImportsDir is the directory holding cached import sources, a sibling of the toolchain cache under CacheRoot.
func (*RemoteResolver) Resolve¶
Resolve fetches the repo named by ref, caches it, and returns a Source rooted at the import's subdir, with FS and Commit always set. A UB library also gets its content Hash set for project-lock integrity.
type Resolution¶
type Resolution struct {
Kind ResolutionKind
LocalAlias string
Ref ImportRef
Path string
Version string
CanonicalKey string
SourcePath string
ModulePath string
ModuleRootPath string
GoImportPath 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¶
func WalkUB(
refs map[string]ImportRef, resolver Resolver, v UBVisitor, versions map[string]string,
) ([]Resolution, error)
WalkUB walks refs and every UB library they transitively reach, invoking the visitor for each import. The returned slice mirrors refs in resolved form, alias-sorted, so callers can build their own alias-to-resolution map without per-site visitor callbacks. Cycles through UB libraries are reported as errors.
versions maps a repository URL to the version selected for it in project-lock; every remote import is walked at its repository's selected version. A remote import whose repository is not in the map has no version and is an error: project-lock must supply it.
func WalkUBFrom¶
func WalkUBFrom(
refs map[string]ImportRef,
resolver Resolver,
v UBVisitor,
versions map[string]string,
source *Source,
) ([]Resolution, error)
WalkUBFrom is WalkUB with the package source that declared refs.
type ResolutionKind¶
ResolutionKind tags how an import was resolved.
type Resolver¶
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
LocalPath string
Commit string
ProjectFS fs.FS
ProjectPath string
ProjectSubdir string
PackageSubdir string
ModuleRootPath string
ModulePath string
GoImportPath string
}
Source is the file tree of a resolved import, rooted at the imported package directory. For remote imports, Commit records the resolved git commit. Path is the on-disk package directory the dev CLI uses for compile-time inspection of Go-library source. LocalPath retains the local import path used for stable generated names and source locations.
func ResolveImportFrom¶
ResolveImportFrom resolves ref using parent source context when available.
func ResolveLocalSource¶
ResolveLocalSource resolves a local import from the package source that declared it. On-disk sources resolve through their Path; virtual sources resolve paths that stay within their fs.FS root.
type SourceClassification¶
SourceClassification is the import-source category and related facts.
func ClassifySource¶
ClassifySource classifies a resolved source for import walkers.
type SourceKind¶
SourceKind classifies a resolved import source.
type SyntaxDependency¶
type SyntaxDependency struct {
Scope string
Label string
Kind SyntaxDependencyKind
Path string
Ref ImportRef
}
SyntaxDependency is one dependency reference from typed source.
func ExtractSyntaxBodyLibraryConfigDeps¶
ExtractSyntaxBodyLibraryConfigDeps parses library-config input type refs in a body.
func ExtractSyntaxDependencies¶
ExtractSyntaxDependencies walks a typed syntax file and parses dependency refs.
type SyntaxDependencyKind¶
SyntaxDependencyKind classifies a typed source dependency.
type SyntaxImport¶
SyntaxImport is one parsed import from a typed syntax file.
func ExtractSyntaxImports¶
ExtractSyntaxImports walks a typed syntax file and parses every import.
type UBLibrary¶
type UBLibrary struct {
SyntaxBodies map[string]map[string]syntax.FactoryBody
SourceFiles map[string]syntax.SourceFileSpec
BodyImports map[string]map[string][]Resolution
Entries []CompositeEntry
Source *Source
}
UBLibrary has everything the visitor needs about a UB library the first time the walker reaches it. SyntaxBodies maps node kind and composite name to typed source declarations. SourceFiles maps parser filenames to source metadata for syntax-body spans. BodyImports maps the same kind and name to the resolved imports declared by that body, in alias-sorted order so callers see a stable view across runs.
func ParseUBLibrarySource¶
ParseUBLibrarySource reads a UB library's composite bodies from source-declared composite export files.
func (*UBLibrary) CompositeEntries¶
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, modulePath, 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.