pkg

package
v0.14.1 Latest Latest
Warning

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

 Go to latest Published: Apr 21, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package pkg implements the AILANG package system: manifests, lock files, dependency resolution, and package loading.

Index

Constants

View Source 
const DefaultRegistryURL = "https://storage.googleapis.com/ailang-registry"

DefaultRegistryURL is the default AILANG package registry.

View Source 
const LockFileName = "ailang.lock"

LockFileName is the canonical lock file name.

View Source 
const LockFileSchema = "ailang.lock/v1"

LockFileSchema is the schema identifier for lock files.

View Source 
const ManifestFile = "ailang.toml"

ManifestFile is the canonical manifest filename.

View Source 
const VersionHistorySchema = "ailang.version-history/v1"

VersionHistorySchema is the canonical schema identifier for history.json.

Variables

This section is empty.

Functions

func BuildDependencyTree 

func BuildDependencyTree(manifest *PackageManifest, rootDir string) (string, error)

BuildDependencyTree returns a printable dependency tree string.

func BumpSemver 

func BumpSemver(version, bumpType string) (string, error)

BumpSemver increments a version string by the specified bump type. bumpType must be "patch", "minor", or "major".

func CachedPackagePath 

func CachedPackagePath(name, version string) (string, error)

CachedPackagePath returns the cache path for a specific package version.

func CheckEffectCeiling 

func CheckEffectCeiling(pkgName string, functionEffects []string, maxEffects []string) error

CheckEffectCeiling validates that the given effects do not exceed a package's declared [effects].max ceiling. Returns nil if within bounds or if no ceiling.

func ContentHash 

func ContentHash(dir string) (string, error)

ContentHash computes a SHA256 hash over all .ail source files in dir, sorted by relative path. Same files in same order = same hash.

func CreateTarball 

func CreateTarball(packageDir string) ([]byte, error)

CreateTarball creates a deterministic tar.gz of a package directory. Includes: ailang.toml, *.ail files, AGENT.md. Excludes: .git, tests/, ailang.lock. Files are sorted and timestamps zeroed for determinism.

func ExtractTarball 

func ExtractTarball(data []byte, destDir string) error

ExtractTarball extracts a tar.gz to a destination directory.

func FindManifest 

func FindManifest(dir string) string

FindManifest walks up from dir looking for ailang.toml. Returns the directory containing it, or empty string if not found.

func FormatVersionConstraint 

func FormatVersionConstraint(version string) string

FormatVersionConstraint creates a >=X.Y.Z constraint from a version string.

func InitManifest 

func InitManifest(dir, name, ailangVersion string) error

InitManifest creates a default ailang.toml in the given directory. ailangVersion is the current AILANG compiler version (used to set the ailang constraint). Pass empty string to omit the constraint.

func InterfaceHash 

func InterfaceHash(m *PackageManifest) string

InterfaceHash computes a SHA256 hash over a package's public interface: package name, edition, sorted exported module list, and sorted max effects. This hash stays the same when only internal code changes — it only changes when the package's public surface (exports, effects) changes.

Explicitly excluded: source formatting, comments, internal modules, declaration order, source file contents.

func IsGhostEffect 

func IsGhostEffect(name string) bool

IsGhostEffect returns true if the named effect is a ghost effect. Ghost effects are invisible to callers and don't need ceiling declarations.

func ParseSemver 

func ParseSemver(version string) (semverTuple, error)

ParseSemver parses a version string like "0.9.5" or "v0.9.5" into components. Returns an error if the format is invalid.

func ParseVersionConstraint 

func ParseVersionConstraint(constraint string) (string, error)

ParseVersionConstraint extracts the minimum version from a constraint string. Supported format: ">=X.Y.Z" (only >= is supported, no ranges). Returns the minimum version string.

func RegistryCacheDir 

func RegistryCacheDir() (string, error)

RegistryCacheDir returns the local cache directory for registry packages.

func SatisfiesAILANGVersion 

func SatisfiesAILANGVersion(requirement, currentVersion string) (bool, error)

SatisfiesAILANGVersion checks if currentVersion meets a package's AILANG requirement. Returns true if:

  • requirement is empty (no constraint — backward compat)
  • currentVersion is "dev" or "unknown" (local builds bypass checks)
  • currentVersion >= required minimum

func TarballHash 

func TarballHash(data []byte) string

TarballHash computes SHA256 of tarball bytes.

Types

type Dependency 

type Dependency struct {
	Version string `toml:"version,omitempty"`
	Path    string `toml:"path,omitempty"`
	Git     string `toml:"git,omitempty"`    // git repo URL
	Tag     string `toml:"tag,omitempty"`    // git tag (e.g., "auth-v0.1.0")
	Rev     string `toml:"rev,omitempty"`    // git commit hash (overrides tag)
	Subdir  string `toml:"subdir,omitempty"` // path within git repo (e.g., "packages/auth")
}

Dependency can be a version string, path table, or git table.

func (*Dependency) UnmarshalTOML 

func (d *Dependency) UnmarshalTOML(data interface{}) error

UnmarshalTOML implements custom TOML unmarshalling for Dependency. Supports: 

"sunholo/json" = "0.3.1"                                                 (string → version)
"shared/utils" = { path = "../utils" }                                   (table → path dep)
"sunholo/auth" = { git = "https://...", subdir = "packages/auth", tag = "v0.1.0" }  (table → git dep)

type EffectConfig 

type EffectConfig struct {
	Max []string `toml:"max"`
}

EffectConfig holds the [effects] section.

type ExportConfig 

type ExportConfig struct {
	Modules []string `toml:"modules"`
}

ExportConfig holds the [exports] section.

type GitCache 

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

GitCache manages cached git clones for git-based dependencies. Clones are stored in ~/.ailang/cache/git/<url-hash>/.

func NewGitCache 

func NewGitCache() (*GitCache, error)

NewGitCache creates a cache rooted at ~/.ailang/cache/git/.

func (*GitCache) CacheDir 

func (gc *GitCache) CacheDir(gitURL string) string

CacheDir returns the deterministic cache directory for a git URL.

func (*GitCache) Resolve 

func (gc *GitCache) Resolve(gitURL, tag, rev, subdir string) (localPath string, resolvedRev string, err error)

Resolve clones or fetches a git repo and checks out the specified tag or rev. Returns the local path to the package (including subdir) and the resolved commit hash.

type HistoryEntry 

type HistoryEntry struct {
	Timestamp string `json:"timestamp"`
	Kind      string `json:"kind"`   // Message kind or action type
	From      string `json:"from"`   // Who sent/did it
	Title     string `json:"title"`  // Brief description
	Detail    string `json:"detail"` // Full content
	Status    string `json:"status"` // "received", "acknowledged", "completed", "failed"
}

HistoryEntry is a single event in the version's message/action trail.

type IndexEntry 

type IndexEntry struct {
	Name              string   `json:"name"`
	Latest            string   `json:"latest"`
	Versions          []string `json:"versions"`
	AISummary         string   `json:"ai_summary"`
	Tags              []string `json:"tags"`
	Effects           []string `json:"effects"`
	Stability         string   `json:"stability"`
	Exports           []string `json:"exports"`
	ContractsVerified int      `json:"contracts_verified"`
	HasAgentDoc       bool     `json:"has_agent_doc"`
	Dependencies      []string `json:"dependencies,omitempty"`   // Package names this depends on (M-PKG-AUTONOMOUS-UPDATES)
	LastUpdated       string   `json:"last_updated,omitempty"`   // When latest version was published
	UpdatedBy         string   `json:"updated_by,omitempty"`     // "human", "agent", or agent ID
	LatestSummary     string   `json:"latest_summary,omitempty"` // From history.json summary
	Repository        string   `json:"repository,omitempty"`     // Source code URL (M-PKG-METADATA-URLS)
	Homepage          string   `json:"homepage,omitempty"`       // Documentation/project homepage
	LicenseURL        string   `json:"license_url,omitempty"`    // Full license text URL
}

IndexEntry is a package listing in the registry index.

type LockFile 

type LockFile struct {
	Schema        string          `json:"schema"`
	Version       string          `json:"schema_version"`
	AILANGVersion string          `json:"ailang_version,omitempty"` // AILANG version that generated this lockfile
	GeneratedAt   time.Time       `json:"generated_at"`
	Generator     string          `json:"generator"`
	Packages      []LockedPackage `json:"packages"`
}

LockFile represents the resolved dependency graph.

func LoadLockFile 

func LoadLockFile(dir string) (*LockFile, error)

LoadLockFile reads and validates a lock file from a directory.

func LoadLockFileFromPath 

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

LoadLockFileFromPath reads and validates a lock file from a specific path.

func NewLockFile 

func NewLockFile(packages []LockedPackage, generator string) *LockFile

NewLockFile creates a lock file from resolved packages.

func (*LockFile) FindPackage 

func (lf *LockFile) FindPackage(name string) (*LockedPackage, bool)

FindPackage looks up a package by name in the lock file.

func (*LockFile) Save 

func (lf *LockFile) Save(dir string) error

Save writes the lock file as deterministic JSON.

func (*LockFile) Validate 

func (lf *LockFile) Validate() error

Validate checks the lock file for consistency.

func (*LockFile) ValidateAgainstManifest 

func (lf *LockFile) ValidateAgainstManifest(m *PackageManifest) error

ValidateAgainstManifest checks that the lock file is consistent with a manifest. Returns an error if the manifest declares dependencies not in the lock file.

func (*LockFile) ValidateContentHashes 

func (lf *LockFile) ValidateContentHashes() error

ValidateContentHashes re-computes content hashes for all path dependencies and verifies they match the lock file. Returns an error if any dependency has changed since the lock file was generated.

type LockedPackage 

type LockedPackage struct {
	Name          string   `json:"name"`
	Version       string   `json:"version"`
	AILANG        string   `json:"ailang,omitempty"` // Minimum AILANG version from package manifest
	ContentHash   string   `json:"content_hash"`
	InterfaceHash string   `json:"interface_hash,omitempty"`
	Source        string   `json:"source"` // "path", "git", or "registry"
	Path          string   `json:"path,omitempty"`
	GitURL        string   `json:"git_url,omitempty"`
	GitRev        string   `json:"git_rev,omitempty"`
	GitSubdir     string   `json:"git_subdir,omitempty"`
	Effects       []string `json:"effects"`
	Exports       []string `json:"exports"`
}

LockedPackage is a resolved dependency entry in the lock file.

type MetadataManifest 

type MetadataManifest struct {
	Edition     string   `json:"edition"`
	AILANG      string   `json:"ailang,omitempty"` // Minimum AILANG version (e.g., ">=0.9.5")
	EffectsMax  []string `json:"effects_max"`
	Exports     []string `json:"exports"`
	Stability   string   `json:"stability"`
	AISummary   string   `json:"ai_summary"`
	HasAgentDoc bool     `json:"has_agent_doc"`
	Repository  string   `json:"repository,omitempty"`  // Source code URL (M-PKG-METADATA-URLS)
	Homepage    string   `json:"homepage,omitempty"`    // Documentation/project homepage
	LicenseURL  string   `json:"license_url,omitempty"` // Full license text URL
}

MetadataManifest is the manifest section of metadata.json.

type PackageInfo 

type PackageInfo struct {
	Name         string `toml:"name"`
	Version      string `toml:"version"`
	Edition      string `toml:"edition"`
	AILANG       string `toml:"ailang"`        // Minimum AILANG version required (e.g., ">=0.9.5")
	ModulePrefix string `toml:"module_prefix"` // Optional: maps existing module paths to package namespace
	Description  string `toml:"description"`
	License      string `toml:"license"`
}

PackageInfo holds the [package] section.

type PackageLoader 

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

PackageLoader resolves package imports against a lock file.

func NewPackageLoader 

func NewPackageLoader(lf *LockFile, rootDir string) *PackageLoader

NewPackageLoader creates a loader from a lock file and root directory.

func (*PackageLoader) EffectCeiling 

func (pl *PackageLoader) EffectCeiling(pkgName string) []string

EffectCeiling returns the max effects declared by a package, or nil if no ceiling is declared (meaning all effects are allowed).

func (*PackageLoader) HasPackage 

func (pl *PackageLoader) HasPackage(pkgName string) bool

HasPackage returns true if the named package exists in the lock file.

func (*PackageLoader) LoadManifestByName 

func (pl *PackageLoader) LoadManifestByName(pkgName string) (*PackageManifest, error)

LoadManifestByName loads a package's manifest by its name. Returns the cached manifest or loads it from the package directory.

func (*PackageLoader) ResolveImport 

func (pl *PackageLoader) ResolveImport(importPath string) (string, error)

ResolveImport resolves a package import path to a source file path. importPath is the path without the pkg/ prefix: "vendor/name/module" Returns the absolute path to the .ail source file.

type PackageManifest 

type PackageManifest struct {
	Package      PackageInfo            `toml:"package"`
	Exports      ExportConfig           `toml:"exports"`
	Dependencies map[string]Dependency  `toml:"dependencies"`
	DevDeps      map[string]Dependency  `toml:"dependencies_dev"`
	Effects      EffectConfig           `toml:"effects"`
	Metadata     map[string]interface{} `toml:"metadata"`
	Stability    StabilityConfig        `toml:"stability"`
}

PackageManifest represents the contents of an ailang.toml file.

func LoadManifest 

func LoadManifest(dir string) (*PackageManifest, error)

LoadManifest reads and validates an ailang.toml from the given directory.

func LoadManifestFile 

func LoadManifestFile(path string) (*PackageManifest, error)

LoadManifestFile reads and validates an ailang.toml from a specific path.

func (*PackageManifest) IsGitDep 

func (m *PackageManifest) IsGitDep(name string) bool

IsGitDep returns true if the named dependency is a git dependency.

func (*PackageManifest) IsPathDep 

func (m *PackageManifest) IsPathDep(name string) bool

IsPathDep returns true if the named dependency is a path dependency.

func (*PackageManifest) MapImportToModulePath 

func (m *PackageManifest) MapImportToModulePath(importPath string) string

MapImportToModulePath converts a canonical import path to the local module path. If module_prefix is set, remaps "vendor/name/subpath" → "prefix/subpath". If not set, returns the import path unchanged.

func (*PackageManifest) MapModuleToImportPath 

func (m *PackageManifest) MapModuleToImportPath(modulePath string) string

MapModuleToImportPath converts a local module path to the canonical import path. If module_prefix is set, remaps "prefix/subpath" → "vendor/name/subpath". If not set, returns the module path unchanged.

func (*PackageManifest) Validate 

func (m *PackageManifest) Validate() error

Validate checks the manifest for required fields and consistency.

type PackageMetadata 

type PackageMetadata struct {
	Schema      string           `json:"schema"`
	Name        string           `json:"name"`
	Version     string           `json:"version"`
	PublishedAt string           `json:"published_at"`
	PublishedBy string           `json:"published_by"`
	ContentHash string           `json:"content_hash"`
	InterfHash  string           `json:"interface_hash"`
	TarballHash string           `json:"tarball_hash"`
	TarballSize int64            `json:"tarball_size_bytes"`
	Validation  ValidationResult `json:"validation"`
	Manifest    MetadataManifest `json:"manifest"`
	Provenance  *ProvenanceInfo  `json:"provenance,omitempty"` // M-PKG-AUTONOMOUS-UPDATES
}

PackageMetadata is the per-version metadata.json from the registry.

type PackageSources 

type PackageSources struct {
	// Dir is the absolute path to the package directory.
	Dir string

	// Manifest is the parsed ailang.toml.
	Manifest *PackageManifest

	// SourceFiles maps module paths to their .ail file paths (absolute).
	// e.g., "sunholo/billing_store/core" -> "/path/to/src/core.ail"
	SourceFiles map[string]string

	// TestFiles lists discovered *_test.ail files (absolute paths).
	TestFiles []string

	// OrphanFiles lists .ail files not matching any exported module.
	OrphanFiles []string

	// MissingModules lists modules declared in [exports] but without source files.
	MissingModules []string
}

PackageSources holds the discovered source files and metadata for a package.

func DiscoverPackageSources 

func DiscoverPackageSources(dir string) (*PackageSources, error)

DiscoverPackageSources reads ailang.toml from dir and discovers all source and test files. It maps exported module paths to source files, identifies test files, and reports missing modules and orphan files.

func (*PackageSources) AllSourcePaths 

func (ps *PackageSources) AllSourcePaths() []string

AllSourcePaths returns all source file paths (not test files) in deterministic order.

type ProvenanceInfo 

type ProvenanceInfo struct {
	TriggerMessageID string   `json:"trigger_message_id,omitempty"` // Message that started this update
	CorrelationIDs   []string `json:"correlation_ids,omitempty"`    // Full message chain
	AgentTraceID     string   `json:"agent_trace_id,omitempty"`     // OTEL trace ID
	ChainID          string   `json:"chain_id,omitempty"`           // Observatory chain ID
	ApprovedBy       string   `json:"approved_by,omitempty"`        // Human approver GitHub handle
	ApprovedAt       string   `json:"approved_at,omitempty"`        // ISO 8601 timestamp
	AutoApproved     bool     `json:"auto_approved"`                // true for class A
	ChangeClass      string   `json:"change_class,omitempty"`       // "A", "B", or "C"
	PreviousVersion  string   `json:"previous_version,omitempty"`   // Version before this update
}

ProvenanceInfo records who/what triggered a package version and the approval chain. Stored in PackageMetadata for audit trail. All fields optional for backward compat.

type RegistryClient 

type RegistryClient struct {
	BaseURL string
	// contains filtered or unexported fields
}

RegistryClient fetches packages and metadata from the AILANG registry.

func NewRegistryClient 

func NewRegistryClient() *RegistryClient

NewRegistryClient creates a client using AILANG_REGISTRY env var or default URL.

func (*RegistryClient) FetchIndex 

func (rc *RegistryClient) FetchIndex() (*RegistryIndex, error)

FetchIndex downloads and parses the registry index.json. Uses ETag caching — returns cached version if unchanged.

func (*RegistryClient) FetchMetadata 

func (rc *RegistryClient) FetchMetadata(name, version string) (*PackageMetadata, error)

FetchMetadata downloads the metadata.json for a specific package version.

func (*RegistryClient) FetchPackage 

func (rc *RegistryClient) FetchPackage(name, version string) ([]byte, error)

FetchPackage downloads a package tarball from the registry.

func (*RegistryClient) ResolveLatestVersion 

func (rc *RegistryClient) ResolveLatestVersion(name string) (string, error)

ResolveLatestVersion looks up the latest version of a package from the registry index. Returns the exact version string (e.g., "0.3.2").

func (*RegistryClient) SearchPackages 

func (rc *RegistryClient) SearchPackages(query string, tagFilter string) ([]IndexEntry, error)

SearchPackages searches the index by keyword matching on name, ai_summary, and tags.

type RegistryIndex 

type RegistryIndex struct {
	Schema    string       `json:"schema"`
	UpdatedAt string       `json:"updated_at"`
	Packages  []IndexEntry `json:"packages"`
}

RegistryIndex is the top-level index.json from the registry.

func (*RegistryIndex) FindDependents 

func (idx *RegistryIndex) FindDependents(pkgName string) []string

FindDependents returns the names of all packages in the index that list the given package as a dependency.

type ResolvedPackage 

type ResolvedPackage struct {
	Name          string
	Version       string
	AILANG        string // Minimum AILANG version from package manifest
	ContentHash   string
	InterfaceHash string
	Source        string // "path", "git", or "registry"
	Path          string // absolute path for path/git deps
	GitURL        string // git repo URL (git deps only)
	GitRev        string // resolved commit hash (git deps only)
	GitSubdir     string // path within repo (git deps only)
	Effects       []string
	Exports       []string
}

ResolvedPackage is a fully resolved dependency with computed hash.

func ResolveDependencies 

func ResolveDependencies(manifest *PackageManifest, rootDir string) ([]ResolvedPackage, error)

ResolveDependencies resolves all dependencies from a manifest. rootDir is the directory containing the manifest. Returns resolved packages in topological order.

type StabilityConfig 

type StabilityConfig struct {
	Level string `toml:"level"`
}

StabilityConfig holds the [stability] section.

type ValidationResult 

type ValidationResult struct {
	Compiles          bool   `json:"compiles"`
	EffectsValid      bool   `json:"effects_valid"`
	ContractsVerified int    `json:"contracts_verified"`
	ContractsTotal    int    `json:"contracts_total"`
	ContractsSkipped  int    `json:"contracts_skipped"`
	AILANGVersion     string `json:"ailang_version"`
}

ValidationResult records what the validator checked.

type VersionConflictError 

type VersionConflictError struct {
	Package          string // e.g., "sunholo/firestore"
	DirectVersion    string // root manifest's version (empty if not a direct dep)
	ExistingVersion  string // version already resolved
	RequestedVersion string // conflicting version requested
	RequestedBy      string // package that requested the conflicting version
}

VersionConflictError is returned when the dependency graph has incompatible version requirements for the same package.

func (*VersionConflictError) Error 

func (e *VersionConflictError) Error() string

type VersionHistory 

type VersionHistory struct {
	Schema    string         `json:"schema"`     // "ailang.version-history/v1"
	Package   string         `json:"package"`    // "sunholo/auth"
	Version   string         `json:"version"`    // "0.2.0"
	Previous  string         `json:"previous"`   // "0.1.0"
	CreatedAt string         `json:"created_at"` // ISO 8601
	Messages  []HistoryEntry `json:"messages"`   // Ordered message trail
	Summary   string         `json:"summary"`    // AI-generated 1-line summary
}

VersionHistory records the full message and action trail for a published version. Stored as history.json in the registry, surfaced on the website for package discovery.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.