package resolve¶

import "github.com/cloudboss/unobin/pkg/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¶

var ErrEmptyImportRef = errors.New("empty import reference")

ErrEmptyImportRef is returned when the source string is empty.

Functions¶

func ContainsFactorySource¶

func ContainsFactorySource(s *Source) bool

ContainsFactorySource reports whether s has a root file that declares a runnable factory instead of an importable library.

func ExtractSyntaxBodyImports¶

func ExtractSyntaxBodyImports(body syntax.FactoryBody) (map[string]ImportRef, []error)

ExtractSyntaxBodyImports parses the imports declared by a typed factory body.

func GitRef¶

func GitRef(ref *RemoteImport) string

GitRef returns the first git ref used to fetch ref.

func HasCompositeExports¶

func HasCompositeExports(s *Source) bool

HasCompositeExports reports whether s has source-declared composite exports.

func IsGoLibrary¶

func IsGoLibrary(s *Source) bool

IsGoLibrary reports whether s looks like a Go library package or module.

func IsUBLibrary¶

func IsUBLibrary(s *Source) bool

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¶

func LocalGoImportError(alias, path string, source *Source) error

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¶

func SplitRepoSubdir(s string) (url, subdir string, err error)

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¶

func UBKey(ref ImportRef) string

UBKey is the dedup key for a UB-library import. Remote imports key on URL, subdir, and version; the `//\` segment is included only when the import names a subdirectory, so root-of-repo refs read cleanly in cycle errors and other diagnostics. Local imports key on path.

func ValidateGoModulePath¶

func ValidateGoModulePath(r *RemoteImport, modulePath string) error

ValidateGoModulePath checks a discovered Go module path against a remote import version.

func ValidateSyntaxCompositeBody¶

func ValidateSyntaxCompositeBody(kind, typeName string, body syntax.FactoryBody) []error

ValidateSyntaxCompositeBody checks a typed composite body against the requirements for its declared kind.

func WithDefaultScheme¶

func WithDefaultScheme(url string) string

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
}

type ContextResolver¶

type ContextResolver interface {
    ResolveFrom(ref ImportRef, parent *Source) (*Source, error)
}

ContextResolver resolves an import from the package source that declared it.

type ImportRef¶

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

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

func ParseImportRef¶

func ParseImportRef(raw string) (ImportRef, error)

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.

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¶

func NewLocalResolver(root string) *LocalResolver

NewLocalResolver returns a LocalResolver rooted at root. Pass the directory containing the factory or library files that own the imports.

func (*LocalResolver) Resolve¶

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

Resolve implements Resolver. The ref must be a *LocalImport; remote refs return an error so a misrouted call is reported clearly.

func (*LocalResolver) ResolveFrom¶

func (r *LocalResolver) ResolveFrom(ref ImportRef, parent *Source) (*Source, error)

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¶

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/\/\/\/`. `NewRemoteResolver` defaults it to `\/unobin`.

func NewRemoteResolver¶

func NewRemoteResolver() (*RemoteResolver, error)

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¶

func (r *RemoteResolver) CachedSource(ref *RemoteImport, commit string) (*Source, bool, error)

CachedSource returns source data for an existing cached commit without contacting git.

func (*RemoteResolver) CleanImports¶

func (r *RemoteResolver) CleanImports() (string, error)

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¶

func (r *RemoteResolver) ImportsDir() string

ImportsDir is the directory holding cached import sources, a sibling of the toolchain cache under CacheRoot.

func (*RemoteResolver) Resolve¶

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

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¶

type ResolutionKind int

ResolutionKind tags how an import was resolved.

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

    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.

func ResolveLocalSource¶

func ResolveLocalSource(li *LocalImport, parent *Source) (*Source, error)

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¶

type SourceClassification struct {
    Kind                SourceKind
    HasCompositeExports bool
}

SourceClassification is the import-source category and related facts.

func ClassifySource¶

func ClassifySource(source *Source) SourceClassification

ClassifySource classifies a resolved source for import walkers.

type SourceKind¶

type SourceKind int

SourceKind classifies a resolved import source.

type SyntaxImport¶

type SyntaxImport struct {
    Scope string
    Alias string
    Ref   ImportRef
}

SyntaxImport is one parsed import from a typed syntax file.

func ExtractSyntaxImports¶

func ExtractSyntaxImports(f *syntax.File) ([]SyntaxImport, []error)

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
}

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¶

func ParseUBLibrarySource(source *Source) (*UBLibrary, error)

ParseUBLibrarySource reads a UB library's composite bodies from source-declared composite export files.

func (*UBLibrary) CompositeEntries¶

func (l *UBLibrary) CompositeEntries() []CompositeEntry

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.