chore: added Pallas compatible comments to core

chore: improvement of Pallas compatible comments to core

chore: fixing line breaks

chore: improving comments based on review

chore: commented each and every function and struct in the project

fix typo

revert deletion of //export comments

added a few Returns: statements

fixes agreed on in review process

missing file in last commit

api/download.go

@@ -11,7 +11,7 @@ import (
 	"strings"
 )
 
-// retrieves the Source directory of a given Source
+// Generate the destination path for the source based on its type and module name
 func GetSourcePath(source Source, moduleName string) string {
 	switch source.Type {
 	case "git":
@@ -30,8 +30,7 @@ func GetSourcePath(source Source, moduleName string) string {
 	return ""
 }
 
-// DownloadSource downloads a source to the downloads directory
-// according to its type (git, tar, ...)
+// Download the source based on its type and validate its checksum
 func DownloadSource(downloadPath string, source Source, moduleName string) error {
 	fmt.Printf("Downloading source: %s\n", source.URL)
 
@@ -60,6 +59,7 @@ func DownloadSource(downloadPath string, source Source, moduleName string) error
 	}
 }
 
+// Clone a specific tag from a Git repository to the destination directory
 func gitCloneTag(url, tag, dest string) error {
 	cmd := exec.Command(
 		"git",
@@ -71,6 +71,7 @@ func gitCloneTag(url, tag, dest string) error {
 	return cmd.Run()
 }
 
+// Retrieve the latest Git repository commit hash for a given branch from the destination directory
 func gitGetLatestCommit(branch, dest string) (string, error) {
 	cmd := exec.Command("git", "--no-pager", "log", "-n", "1", "--pretty=format:\"%H\"", branch)
 	cmd.Dir = dest
@@ -82,6 +83,7 @@ func gitGetLatestCommit(branch, dest string) (string, error) {
 	return strings.Trim(string(latest_tag), "\""), nil
 }
 
+// Check out a specific Git repository branch or commit in the destination directory
 func gitCheckout(value, dest string) error {
 	cmd := exec.Command("git", "checkout", value)
 	cmd.Stdout = os.Stdout
@@ -90,8 +92,7 @@ func gitCheckout(value, dest string) error {
 	return cmd.Run()
 }
 
-// DownloadGitSource downloads a git source to the downloads directory
-// and checks out the commit or tag
+// Download a Git source repository based on the specified tag, branch, or commit
 func DownloadGitSource(downloadPath string, source Source, moduleName string) error {
 	fmt.Printf("Downloading git source: %s\n", source.URL)
 
@@ -136,7 +137,7 @@ func DownloadGitSource(downloadPath string, source Source, moduleName string) er
 	return gitCheckout(source.Commit, dest)
 }
 
-// DownloadTarSource downloads a tar archive to the downloads directory
+// Download a tarball from the specified URL and save it to the destination path
 func DownloadTarSource(downloadPath string, source Source, moduleName string) error {
 	fmt.Printf("Source is tar: %s\n", source.URL)
 	// Create the destination path
@@ -165,8 +166,7 @@ func DownloadTarSource(downloadPath string, source Source, moduleName string) er
 	return nil
 }
 
-// MoveSources moves all sources from the downloads directory to the
-// sources directory
+// Move downloaded sources from the download path to the sources path
 func MoveSources(downloadPath string, sourcesPath string, sources []Source, moduleName string) error {
 	fmt.Println("Moving sources")
 
@@ -180,9 +180,9 @@ func MoveSources(downloadPath string, sourcesPath string, sources []Source, modu
 	return nil
 }
 
-// MoveSource moves a source from the downloads directory to the
-// sources directory, by extracting if a tar archive or moving if a
-// git repository
+// Move or extract a source from the download path to the sources path depending on its type
+// tarballs: extract
+// git repositories: move
 func MoveSource(downloadPath string, sourcesPath string, source Source, moduleName string) error {
 	fmt.Printf("Moving source: %s\n", moduleName)
 
@@ -211,7 +211,7 @@ func MoveSource(downloadPath string, sourcesPath string, source Source, moduleNa
 	}
 }
 
-// checksumValidation validates the checksum of a file
+// Validate the checksum of the downloaded file
 func checksumValidation(source Source, path string) error {
 	// No checksum provided
 	if len(strings.TrimSpace(source.Checksum)) == 0 {
@@ -243,6 +243,8 @@ func checksumValidation(source Source, path string) error {
 	return nil
 }
 
+// Download a file source from a URL and save it to the specified download path.
+// Create necessary directories and handle file naming based on the URL extension.
 func DownloadFileSource(downloadPath string, source Source, moduleName string) error {
 	fmt.Printf("Source is file: %s\n", source.URL)
 

api/finalize-scopes.go

@@ -15,6 +15,7 @@ var RUNTIME int32 = 8
 // / Get a read-only filesystem of the Image
 var FS int32 = 16
 
+// Information about the image, recipe, runtime, and file system mountpoint
 type ScopeData struct {
 	ImageName string
 	ImageID   string

api/structs.go

@@ -1,5 +1,6 @@
 package api
 
+// Configuration for a source
 type Source struct {
 	URL         string   `json:"url"`
 	Checksum    string   `json:"checksum"`
@@ -12,6 +13,7 @@ type Source struct {
 	Paths       []string `json:"paths"`
 }
 
+// Configuration for a recipe
 type Recipe struct {
 	Name          string
 	Id            string
@@ -25,6 +27,7 @@ type Recipe struct {
 	Finalize      []interface{}
 }
 
+// Configuration for a stage in the recipe
 type Stage struct {
 	Id          string            `json:"id"`
 	Base        string            `json:"base"`
@@ -48,32 +51,38 @@ const (
 	FinalizePlugin
 )
 
+// Information about a plugin
 type PluginInfo struct {
 	Name string
 	Type PluginType
 }
 
+// Configuration for copying files or directories in a stage
 type Copy struct {
 	From    string
 	SrcDst  map[string]string
 	Workdir string
 }
 
+// Configuration for adding files or directories in a stage
 type Add struct {
 	SrcDst  map[string]string
 	Workdir string
 }
 
+// Configuration for the entrypoint of a container
 type Entrypoint struct {
 	Exec    []string
 	Workdir string
 }
 
+// Configuration for a command to run in the container
 type Cmd struct {
 	Exec    []string
 	Workdir string
 }
 
+// Configuration for commands to run in the container
 type Run struct {
 	Commands []string
 	Workdir  string

cmd/build.go

@@ -11,6 +11,9 @@ import (
 	"github.com/vanilla-os/vib/core"
 )
 
+// Create a new build command for the Cobra CLI
+//
+// Returns: new Cobra command for building a recipe
 func NewBuildCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "build",
@@ -28,6 +31,7 @@ func NewBuildCommand() *cobra.Command {
 	return cmd
 }
 
+// Handle the build command for the Cobra CLI
 func buildCommand(cmd *cobra.Command, args []string) error {
 	commonNames := []string{
 		"recipe.yml",

cmd/compile.go

@@ -9,6 +9,7 @@ import (
 	"github.com/vanilla-os/vib/core"
 )
 
+// Create and return a new compile command for the Cobra CLI
 func NewCompileCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "compile",
@@ -26,6 +27,7 @@ func NewCompileCommand() *cobra.Command {
 	return cmd
 }
 
+// Execute the compile command: compile the given recipe into a container image
 func compileCommand(cmd *cobra.Command, args []string) error {
 	commonNames := []string{
 		"recipe.yml",
@@ -68,6 +70,9 @@ func compileCommand(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
+// Detect the container runtime by checking the system path
+//
+// Returns: runtime name or an empty string if no runtime is found
 func detectRuntime() string {
 	path, _ := exec.LookPath("docker")
 	if path != "" {

cmd/root.go

@@ -23,12 +23,14 @@ var rootCmd = &cobra.Command{
 	Version: Version,
 }
 
+// Initialize the root command with build, test, and compile commands
 func init() {
 	rootCmd.AddCommand(NewBuildCommand())
 	rootCmd.AddCommand(NewTestCommand())
 	rootCmd.AddCommand(NewCompileCommand())
 }
 
+// Execute the root command, handling root user environment setup and privilege dropping
 func Execute() error {
 	if os.Getuid() == 0 {
 		IsRoot = true

cmd/test.go

@@ -7,6 +7,7 @@ import (
 	"github.com/vanilla-os/vib/core"
 )
 
+// Create and return a new test command for the Cobra CLI
 func NewTestCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "test",
@@ -19,6 +20,7 @@ func NewTestCommand() *cobra.Command {
 	return cmd
 }
 
+// Validate the provided recipe by testing it
 func testCommand(cmd *cobra.Command, args []string) error {
 	if len(args) == 0 {
 		return fmt.Errorf("no recipe path specified")

core/build.go

@@ -10,6 +10,7 @@ import (
 	"github.com/vanilla-os/vib/api"
 )
 
+// Add a WORKDIR instruction to the containerfile
 func ChangeWorkingDirectory(workdir string, containerfile *os.File) error {
 	if workdir != "" {
 		_, err := containerfile.WriteString(
@@ -22,6 +23,7 @@ func ChangeWorkingDirectory(workdir string, containerfile *os.File) error {
 	return nil
 }
 
+// Add a WORKDIR instruction to reset to the root directory
 func RestoreWorkingDirectory(workdir string, containerfile *os.File) error {
 	if workdir != "" {
 		_, err := containerfile.WriteString(
@@ -35,7 +37,7 @@ func RestoreWorkingDirectory(workdir string, containerfile *os.File) error {
 	return nil
 }
 
-// BuildRecipe builds a Containerfile from a recipe path
+// Load and build a Containerfile from the specified recipe
 func BuildRecipe(recipePath string) (api.Recipe, error) {
 	// load the recipe
 	recipe, err := LoadRecipe(recipePath)
@@ -63,8 +65,7 @@ func BuildRecipe(recipePath string) (api.Recipe, error) {
 	return *recipe, nil
 }
 
-// BuildContainerfile builds a Containerfile from a recipe
-// and a list of modules commands
+// Generate a Containerfile from the recipe
 func BuildContainerfile(recipe *api.Recipe) error {
 	containerfile, err := os.Create(recipe.Containerfile)
 	if err != nil {
@@ -357,7 +358,7 @@ func BuildContainerfile(recipe *api.Recipe) error {
 	return nil
 }
 
-// BuildModules builds a list of modules commands from a list of modules
+// Build commands for each module in the recipe
 func BuildModules(recipe *api.Recipe, modules []interface{}) ([]ModuleCommand, error) {
 	cmds := []ModuleCommand{}
 	for _, moduleInterface := range modules {
@@ -382,9 +383,7 @@ func BuildModules(recipe *api.Recipe, modules []interface{}) ([]ModuleCommand, e
 	return cmds, nil
 }
 
-// BuildModule builds a module command from a module
-// this is done by calling the appropriate module builder
-// function based on the module type
+// Build a command string for the given module in the recipe
 func BuildModule(recipe *api.Recipe, moduleInterface interface{}) (string, error) {
 	var module Module
 	err := mapstructure.Decode(moduleInterface, &module)

core/compile.go

@@ -10,7 +10,7 @@ import (
 	"github.com/vanilla-os/vib/api"
 )
 
-// CompileRecipe compiles a recipe into a runnable image.
+// Compile and build the recipe using the specified runtime
 func CompileRecipe(recipePath string, runtime string, isRoot bool, origGid int, origUid int) error {
 	recipe, err := BuildRecipe(recipePath)
 	if err != nil {
@@ -56,6 +56,7 @@ func CompileRecipe(recipePath string, runtime string, isRoot bool, origGid int,
 	return nil
 }
 
+// Build an OCI image using the specified recipe through Docker
 func compileDocker(recipe api.Recipe, gid int, uid int) error {
 	docker, err := exec.LookPath("docker")
 	if err != nil {
@@ -75,6 +76,7 @@ func compileDocker(recipe api.Recipe, gid int, uid int) error {
 	return cmd.Run()
 }
 
+// Build an OCI image using the specified recipe through Podman
 func compilePodman(recipe api.Recipe, gid int, uid int) error {
 	podman, err := exec.LookPath("podman")
 	if err != nil {

core/finalize.go

@@ -7,12 +7,14 @@ import (
 	"strings"
 )
 
+// Configuration for storage drivers
 type StorageConf struct {
 	Driver    string
 	Runroot   string
 	Graphroot string
 }
 
+// Retrieve the container storage configuration based on the runtime
 func GetContainerStorage(runtime string) (cstorage.Store, error) {
 	storageconfig := &StorageConf{}
 	if runtime == "podman" {
@@ -50,6 +52,7 @@ func GetContainerStorage(runtime string) (cstorage.Store, error) {
 	return store, err
 }
 
+// Retrieve the image ID for a given image name from the storage
 func GetImageID(name string, store cstorage.Store) (string, error) {
 	images, err := store.Images()
 	if err != nil {
@@ -65,6 +68,7 @@ func GetImageID(name string, store cstorage.Store) (string, error) {
 	return "", fmt.Errorf("image not found")
 }
 
+// Retrieve the top layer ID for a given image ID from the storage
 func GetTopLayerID(imageid string, store cstorage.Store) (string, error) {
 	images, err := store.Images()
 	if err != nil {
@@ -78,6 +82,7 @@ func GetTopLayerID(imageid string, store cstorage.Store) (string, error) {
 	return "", fmt.Errorf("no top layer for id %s found", imageid)
 }
 
+// Mount the image and return the mount directory
 func MountImage(imagename string, imageid string, runtime string) (string, error) {
 	store, err := GetContainerStorage(runtime)
 	if err != nil {

core/resolver_test.go

@@ -8,6 +8,7 @@ import (
 	"github.com/vanilla-os/vib/api"
 )
 
+// Test the DownloadSource function to ensure it downloads and verifies the source file
 func TestDownloadSource(t *testing.T) {
 	tmp := t.TempDir()
 
@@ -29,6 +30,7 @@ func TestDownloadSource(t *testing.T) {
 	defer os.Remove("/tmp/example") // clean up
 }
 
+// Test the DownloadTarSource function to ensure it downloads and verifies the tar file
 func TestDownloadTarSource(t *testing.T) {
 	tmp := t.TempDir()