Merge branch 'main' into feature-tdd-testing-with-mocking

.gitignore

@@ -2,3 +2,4 @@ borg
 *.cube
 .task
 *.datanode
+.idea

cmd/all.go

@@ -63,6 +63,7 @@ var allCmd = &cobra.Command{
 	},
 }
 
+// init registers the 'all' subcommand and its flags.
 func init() {
 	RootCmd.AddCommand(allCmd)
 	allCmd.PersistentFlags().String("output", ".", "Output directory for the DataNodes")

cmd/collect.go

@@ -11,6 +11,7 @@ var collectCmd = &cobra.Command{
 	Long:  `Collect a resource from a git repository, a website, or other URI and store it in a DataNode.`,
 }
 
+// init registers the 'collect' command under the root command.
 func init() {
 	RootCmd.AddCommand(collectCmd)
 }

cmd/collect_github.go

@@ -11,6 +11,7 @@ var collectGithubCmd = &cobra.Command{
 	Long:  `Collect a resource from a GitHub repository, such as a repository or a release.`,
 }
 
+// init registers the 'github' subcommand under the collect command.
 func init() {
 	collectCmd.AddCommand(collectGithubCmd)
 }

cmd/collect_github_release_subcommand.go

@@ -126,6 +126,7 @@ var collectGithubReleaseCmd = &cobra.Command{
 	},
 }
 
+// init registers the 'release' subcommand and its flags under the GitHub command.
 func init() {
 	collectGithubCmd.AddCommand(collectGithubReleaseCmd)
 	collectGithubReleaseCmd.PersistentFlags().String("output", ".", "Output directory for the downloaded file")

cmd/collect_github_repo.go

@@ -84,6 +84,7 @@ var collectGithubRepoCmd = &cobra.Command{
 	},
 }
 
+// init registers the 'repo' subcommand and its flags under the GitHub command.
 func init() {
 	collectGithubCmd.AddCommand(collectGithubRepoCmd)
 	collectGithubRepoCmd.PersistentFlags().String("output", "", "Output file for the DataNode")

cmd/collect_github_repos.go

@@ -7,6 +7,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// collectGithubReposCmd represents the command that lists public repositories for a user or organization.
 var collectGithubReposCmd = &cobra.Command{
 	Use:   "repos [user-or-org]",
 	Short: "Collects all public repositories for a user or organization",
@@ -23,6 +24,7 @@ var collectGithubReposCmd = &cobra.Command{
 	},
 }
 
+// init registers the collectGithubReposCmd subcommand under the GitHub command.
 func init() {
 	collectGithubCmd.AddCommand(collectGithubReposCmd)
 }

cmd/collect_pwa.go

@@ -89,6 +89,7 @@ Example:
 	},
 }
 
+// init registers the 'pwa' command and its flags under the collect command.
 func init() {
 	collectCmd.AddCommand(collectPWACmd)
 	collectPWACmd.Flags().String("uri", "", "The URI of the PWA to collect")

cmd/collect_website.go

@@ -4,11 +4,11 @@ import (
 	"fmt"
 	"os"
 
-	"github.com/schollz/progressbar/v3"
 	"github.com/Snider/Borg/pkg/compress"
 	"github.com/Snider/Borg/pkg/matrix"
 	"github.com/Snider/Borg/pkg/ui"
 	"github.com/Snider/Borg/pkg/website"
+	"github.com/schollz/progressbar/v3"
 
 	"github.com/spf13/cobra"
 )
@@ -83,6 +83,7 @@ var collectWebsiteCmd = &cobra.Command{
 	},
 }
 
+// init registers the 'website' command and its flags under the collect command.
 func init() {
 	collectCmd.AddCommand(collectWebsiteCmd)
 	collectWebsiteCmd.PersistentFlags().String("output", "", "Output file for the DataNode")

cmd/root.go

@@ -30,3 +30,8 @@ func Execute(log *slog.Logger) error {
 	RootCmd.SetContext(context.WithValue(context.Background(), "logger", log))
 	return RootCmd.Execute()
 }
+
+// init configures persistent flags for the root command.
+func init() {
+	RootCmd.PersistentFlags().BoolP("verbose", "v", false, "Enable verbose logging")
+}

cmd/serve.go

@@ -62,6 +62,7 @@ var serveCmd = &cobra.Command{
 	},
 }
 
+// init registers the 'serve' command and its flags under the root command.
 func init() {
 	RootCmd.AddCommand(serveCmd)
 	serveCmd.PersistentFlags().String("port", "8080", "Port to serve the PWA on")

main.go

@@ -7,6 +7,7 @@ import (
 	"github.com/Snider/Borg/pkg/logger"
 )
 
+// main is the entry point of the application, initialises logger, and executes the root command with error handling.
 func main() {
 	verbose, _ := cmd.RootCmd.PersistentFlags().GetBool("verbose")
 	log := logger.New(verbose)

pkg/datanode/datanode.go

@@ -260,19 +260,35 @@ type dataFile struct {
 	modTime time.Time
 }
 
+// Stat returns a FileInfo describing the dataFile.
 func (d *dataFile) Stat() (fs.FileInfo, error) { return &dataFileInfo{file: d}, nil }
+
+// Read implements fs.File by returning EOF for write-only dataFile handles.
 func (d *dataFile) Read(p []byte) (int, error) { return 0, io.EOF }
-func (d *dataFile) Close() error               { return nil }
+
+// Close is a no-op for in-memory dataFile values.
+func (d *dataFile) Close() error { return nil }
 
 // dataFileInfo implements fs.FileInfo for a dataFile.
 type dataFileInfo struct{ file *dataFile }
 
-func (d *dataFileInfo) Name() string       { return path.Base(d.file.name) }
-func (d *dataFileInfo) Size() int64        { return int64(len(d.file.content)) }
-func (d *dataFileInfo) Mode() fs.FileMode  { return 0444 }
+// Name returns the base name of the data file.
+func (d *dataFileInfo) Name() string { return path.Base(d.file.name) }
+
+// Size returns the size of the data file in bytes.
+func (d *dataFileInfo) Size() int64 { return int64(len(d.file.content)) }
+
+// Mode returns the file mode bits for a read-only regular file.
+func (d *dataFileInfo) Mode() fs.FileMode { return 0444 }
+
+// ModTime returns the modification time of the data file.
 func (d *dataFileInfo) ModTime() time.Time { return d.file.modTime }
-func (d *dataFileInfo) IsDir() bool        { return false }
-func (d *dataFileInfo) Sys() interface{}   { return nil }
+
+// IsDir reports whether the FileInfo describes a directory (always false).
+func (d *dataFileInfo) IsDir() bool { return false }
+
+// Sys returns underlying data source (always nil).
+func (d *dataFileInfo) Sys() interface{} { return nil }
 
 // dataFileReader implements fs.File for a dataFile.
 type dataFileReader struct {
@@ -280,13 +296,18 @@ type dataFileReader struct {
 	reader *bytes.Reader
 }
 
+// Stat returns a FileInfo describing the underlying data file.
 func (d *dataFileReader) Stat() (fs.FileInfo, error) { return d.file.Stat() }
+
+// Read reads from the underlying byte slice, initializing the reader on first use.
 func (d *dataFileReader) Read(p []byte) (int, error) {
 	if d.reader == nil {
 		d.reader = bytes.NewReader(d.file.content)
 	}
 	return d.reader.Read(p)
 }
+
+// Close is a no-op for in-memory readers.
 func (d *dataFileReader) Close() error { return nil }
 
 // dirInfo implements fs.FileInfo for an implicit directory.
@@ -295,12 +316,23 @@ type dirInfo struct {
 	modTime time.Time
 }
 
-func (d *dirInfo) Name() string       { return d.name }
-func (d *dirInfo) Size() int64        { return 0 }
-func (d *dirInfo) Mode() fs.FileMode  { return fs.ModeDir | 0555 }
+// Name returns the directory name.
+func (d *dirInfo) Name() string { return d.name }
+
+// Size returns the size for a directory (always 0).
+func (d *dirInfo) Size() int64 { return 0 }
+
+// Mode returns the file mode bits indicating a read-only directory.
+func (d *dirInfo) Mode() fs.FileMode { return fs.ModeDir | 0555 }
+
+// ModTime returns the modification time of the directory.
 func (d *dirInfo) ModTime() time.Time { return d.modTime }
-func (d *dirInfo) IsDir() bool        { return true }
-func (d *dirInfo) Sys() interface{}   { return nil }
+
+// IsDir reports that this FileInfo describes a directory.
+func (d *dirInfo) IsDir() bool { return true }
+
+// Sys returns underlying data source (always nil).
+func (d *dirInfo) Sys() interface{} { return nil }
 
 // dirFile implements fs.File for a directory.
 type dirFile struct {

pkg/github/github.go

@@ -14,14 +14,19 @@ import (
 	"golang.org/x/oauth2"
 )
 
+// Repo is a minimal representation of a GitHub repository used in this package.
 type Repo struct {
 	CloneURL string `json:"clone_url"`
 }
 
+// GetPublicRepos returns clone URLs for all public repositories owned by the given user or org.
+// It uses the public GitHub API endpoint.
 func GetPublicRepos(ctx context.Context, userOrOrg string) ([]string, error) {
 	return GetPublicReposWithAPIURL(ctx, "https://api.github.com", userOrOrg)
 }
 
+// newAuthenticatedClient returns an HTTP client authenticated with a GitHub token if present.
+// If the GITHUB_TOKEN environment variable is not set, it returns http.DefaultClient.
 func newAuthenticatedClient(ctx context.Context) *http.Client {
 	if os.Getenv("BORG_PLEXSUS") == "0" {
 		// Define mock responses for testing
@@ -49,6 +54,8 @@ func newAuthenticatedClient(ctx context.Context) *http.Client {
 	return oauth2.NewClient(ctx, ts)
 }
 
+// GetPublicReposWithAPIURL returns clone URLs for all public repositories for userOrOrg
+// using the specified GitHub API base URL. It transparently follows pagination.
 func GetPublicReposWithAPIURL(ctx context.Context, apiURL, userOrOrg string) ([]string, error) {
 	client := newAuthenticatedClient(ctx)
 	var allCloneURLs []string
@@ -113,6 +120,7 @@ func GetPublicReposWithAPIURL(ctx context.Context, apiURL, userOrOrg string) ([]
 	return allCloneURLs, nil
 }
 
+// findNextURL parses the RFC 5988 Link header and returns the URL with rel="next", if any.
 func findNextURL(linkHeader string) string {
 	links := strings.Split(linkHeader, ",")
 	for _, link := range links {

pkg/logger/logger.go

@@ -5,6 +5,8 @@ import (
 	"os"
 )
 
+// New returns a configured slog.Logger.
+// When verbose is true, the logger emits debug-level logs; otherwise info-level.
 func New(verbose bool) *slog.Logger {
 	level := slog.LevelInfo
 	if verbose {

pkg/pwa/pwa.go

@@ -170,6 +170,7 @@ func DownloadAndPackagePWA(baseURL string, manifestURL string, bar *progressbar.
 	return dn, nil
 }
 
+// resolveURL resolves ref against base and returns the absolute URL.
 func resolveURL(base, ref string) (*url.URL, error) {
 	baseURL, err := url.Parse(base)
 	if err != nil {
@@ -182,6 +183,7 @@ func resolveURL(base, ref string) (*url.URL, error) {
 	return baseURL.ResolveReference(refURL), nil
 }
 
+// downloadAndAddFile downloads the content at fileURL and adds it to the DataNode under internalPath.
 func downloadAndAddFile(dn *datanode.DataNode, fileURL *url.URL, internalPath string, bar *progressbar.ProgressBar) error {
 	client := getHTTPClient()
 	resp, err := client.Get(fileURL.String())

pkg/tarfs/tarfs.go

@@ -67,16 +67,23 @@ type tarFile struct {
 	modTime time.Time
 }
 
-func (f *tarFile) Close() error               { return nil }
+// Close implements http.File by doing nothing for a tar-backed file.
+func (f *tarFile) Close() error { return nil }
+
+// Read reads from the tar-backed file content.
 func (f *tarFile) Read(p []byte) (int, error) { return f.content.Read(p) }
+
+// Seek repositions the read offset within the tar-backed file content.
 func (f *tarFile) Seek(offset int64, whence int) (int64, error) {
 	return f.content.Seek(offset, whence)
 }
 
+// Readdir is unsupported for files and returns an error.
 func (f *tarFile) Readdir(count int) ([]os.FileInfo, error) {
 	return nil, os.ErrInvalid
 }
 
+// Stat returns a FileInfo describing the tar-backed file.
 func (f *tarFile) Stat() (os.FileInfo, error) {
 	return &tarFileInfo{
 		name:    path.Base(f.header.Name),
@@ -92,9 +99,20 @@ type tarFileInfo struct {
 	modTime time.Time
 }
 
-func (i *tarFileInfo) Name() string       { return i.name }
-func (i *tarFileInfo) Size() int64        { return i.size }
-func (i *tarFileInfo) Mode() os.FileMode  { return 0444 }
+// Name returns the base name of the tar-backed file.
+func (i *tarFileInfo) Name() string { return i.name }
+
+// Size returns the size of the tar-backed file in bytes.
+func (i *tarFileInfo) Size() int64 { return i.size }
+
+// Mode returns the file mode bits for a read-only regular file.
+func (i *tarFileInfo) Mode() os.FileMode { return 0444 }
+
+// ModTime returns the file's modification time.
 func (i *tarFileInfo) ModTime() time.Time { return i.modTime }
-func (i *tarFileInfo) IsDir() bool        { return false }
-func (i *tarFileInfo) Sys() interface{}   { return nil }
+
+// IsDir reports whether the FileInfo describes a directory (always false).
+func (i *tarFileInfo) IsDir() bool { return false }
+
+// Sys returns underlying data source (always nil).
+func (i *tarFileInfo) Sys() interface{} { return nil }

pkg/ui/non_interactive_prompter.go

@@ -1,4 +1,3 @@
-
 package ui
 
 import (
@@ -11,21 +10,24 @@ import (
 	"github.com/mattn/go-isatty"
 )
 
+// NonInteractivePrompter periodically prints quotes when stdout is non-interactive.
 type NonInteractivePrompter struct {
-	stopChan    chan struct{}
-	quoteFunc   func() (string, error)
-	started     bool
-	mu          sync.Mutex
-	stopOnce    sync.Once
+	stopChan  chan struct{}
+	quoteFunc func() (string, error)
+	started   bool
+	mu        sync.Mutex
+	stopOnce  sync.Once
 }
 
+// NewNonInteractivePrompter constructs a NonInteractivePrompter using the provided quote function.
 func NewNonInteractivePrompter(quoteFunc func() (string, error)) *NonInteractivePrompter {
 	return &NonInteractivePrompter{
-		stopChan:    make(chan struct{}),
-		quoteFunc:   quoteFunc,
+		stopChan:  make(chan struct{}),
+		quoteFunc: quoteFunc,
 	}
 }
 
+// Start begins periodic quote printing in a background goroutine when not interactive.
 func (p *NonInteractivePrompter) Start() {
 	p.mu.Lock()
 	if p.started {
@@ -60,6 +62,7 @@ func (p *NonInteractivePrompter) Start() {
 	}()
 }
 
+// Stop signals the background goroutine to stop printing quotes.
 func (p *NonInteractivePrompter) Stop() {
 	if p.IsInteractive() {
 		return
@@ -69,6 +72,7 @@ func (p *NonInteractivePrompter) Stop() {
 	})
 }
 
+// IsInteractive reports whether stdout is attached to an interactive terminal.
 func (p *NonInteractivePrompter) IsInteractive() bool {
 	return isatty.IsTerminal(os.Stdout.Fd()) || isatty.IsCygwinTerminal(os.Stdout.Fd())
 }

pkg/ui/progress_writer.go

@@ -1,17 +1,19 @@
-
 package ui
 
 import "github.com/schollz/progressbar/v3"
 
-type progressWriter struct {
+// ProgressWriter updates a progress bar’s description on writes.
+type ProgressWriter struct {
 	bar *progressbar.ProgressBar
 }
 
-func NewProgressWriter(bar *progressbar.ProgressBar) *progressWriter {
-	return &progressWriter{bar: bar}
+// NewProgressWriter creates a writer that sets the progress bar description to the last written line.
+func NewProgressWriter(bar *progressbar.ProgressBar) *ProgressWriter {
+	return &ProgressWriter{bar: bar}
 }
 
-func (pw *progressWriter) Write(p []byte) (n int, err error) {
+// Write implements io.Writer by describing the progress with the provided bytes.
+func (pw *ProgressWriter) Write(p []byte) (n int, err error) {
 	if pw == nil || pw.bar == nil {
 		return len(p), nil
 	}

pkg/ui/quote.go

@@ -1,4 +1,3 @@
-
 package ui
 
 import (
@@ -18,10 +17,12 @@ var (
 	quotesErr    error
 )
 
+// init seeds the random number generator for quote selection.
 func init() {
 	rand.Seed(time.Now().UnixNano())
 }
 
+// Quotes contains categorized sets of quotes used by the UI.
 type Quotes struct {
 	InitWorkAssimilate        []string `json:"init_work_assimilate"`
 	EncryptionServiceMessages []string `json:"encryption_service_messages"`
@@ -43,6 +44,7 @@ type Quotes struct {
 	} `json:"image_related"`
 }
 
+// loadQuotes reads and unmarshals the embedded quotes JSON file.
 func loadQuotes() (*Quotes, error) {
 	quotesFile, err := data.QuotesJSON.ReadFile("quotes.json")
 	if err != nil {
@@ -56,6 +58,7 @@ func loadQuotes() (*Quotes, error) {
 	return &quotes, nil
 }
 
+// getQuotes loads and caches the Quotes on first use, returning the cached instance thereafter.
 func getQuotes() (*Quotes, error) {
 	quotesOnce.Do(func() {
 		cachedQuotes, quotesErr = loadQuotes()
@@ -63,6 +66,7 @@ func getQuotes() (*Quotes, error) {
 	return cachedQuotes, quotesErr
 }
 
+// GetRandomQuote returns a randomly selected quote from all categories.
 func GetRandomQuote() (string, error) {
 	quotes, err := getQuotes()
 	if err != nil {
@@ -84,6 +88,7 @@ func GetRandomQuote() (string, error) {
 	return allQuotes[rand.Intn(len(allQuotes))], nil
 }
 
+// PrintQuote prints a randomly selected quote to stdout in green.
 func PrintQuote() {
 	quote, err := GetRandomQuote()
 	if err != nil {
@@ -94,6 +99,7 @@ func PrintQuote() {
 	c.Println(quote)
 }
 
+// GetVCSQuote returns a random quote from the VCSProcessing category.
 func GetVCSQuote() (string, error) {
 	quotes, err := getQuotes()
 	if err != nil {
@@ -105,6 +111,7 @@ func GetVCSQuote() (string, error) {
 	return quotes.VCSProcessing[rand.Intn(len(quotes.VCSProcessing))], nil
 }
 
+// GetPWAQuote returns a random quote from the PWAProcessing category.
 func GetPWAQuote() (string, error) {
 	quotes, err := getQuotes()
 	if err != nil {
@@ -116,6 +123,7 @@ func GetPWAQuote() (string, error) {
 	return quotes.PWAProcessing[rand.Intn(len(quotes.PWAProcessing))], nil
 }
 
+// GetWebsiteQuote returns a random quote from the CodeRelatedLong category.
 func GetWebsiteQuote() (string, error) {
 	quotes, err := getQuotes()
 	if err != nil {

pkg/website/website.go

@@ -70,6 +70,7 @@ func DownloadAndPackageWebsite(startURL string, maxDepth int, bar *progressbar.P
 	return d.dn, nil
 }
 
+// crawl visits pageURL, saves its content, and follows local links up to maxDepth.
 func (d *Downloader) crawl(pageURL string, depth int) {
 	if depth > d.maxDepth || d.visited[pageURL] {
 		return
@@ -127,6 +128,7 @@ func (d *Downloader) crawl(pageURL string, depth int) {
 	f(doc)
 }
 
+// downloadAsset fetches an asset by URL and stores it in the DataNode.
 func (d *Downloader) downloadAsset(assetURL string) {
 	if d.visited[assetURL] {
 		return
@@ -153,6 +155,7 @@ func (d *Downloader) downloadAsset(assetURL string) {
 	d.dn.AddData(relPath, body)
 }
 
+// getRelativePath returns the path within the DataNode for the given page URL.
 func (d *Downloader) getRelativePath(pageURL string) string {
 	u, err := url.Parse(pageURL)
 	if err != nil {
@@ -161,6 +164,7 @@ func (d *Downloader) getRelativePath(pageURL string) string {
 	return strings.TrimPrefix(u.Path, "/")
 }
 
+// resolveURL resolves ref against base and returns the absolute URL string.
 func (d *Downloader) resolveURL(base, ref string) (string, error) {
 	baseURL, err := url.Parse(base)
 	if err != nil {
@@ -173,6 +177,7 @@ func (d *Downloader) resolveURL(base, ref string) (string, error) {
 	return baseURL.ResolveReference(refURL).String(), nil
 }
 
+// isLocal reports whether pageURL shares the same hostname as the base URL.
 func (d *Downloader) isLocal(pageURL string) bool {
 	u, err := url.Parse(pageURL)
 	if err != nil {
@@ -181,6 +186,7 @@ func (d *Downloader) isLocal(pageURL string) bool {
 	return u.Hostname() == d.baseURL.Hostname()
 }
 
+// isAsset reports whether the URL likely points to a static asset by file extension.
 func isAsset(pageURL string) bool {
 	ext := []string{".css", ".js", ".png", ".jpg", ".jpeg", ".gif", ".svg", ".ico"}
 	for _, e := range ext {