diff --git a/.gitignore b/.gitignore index 1bd3f87..3f2b78b 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ borg *.cube .task *.datanode +.idea diff --git a/cmd/all.go b/cmd/all.go index 1fecf21..7bbd3e9 100644 --- a/cmd/all.go +++ b/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") diff --git a/cmd/collect.go b/cmd/collect.go index 8e3d817..e655c67 100644 --- a/cmd/collect.go +++ b/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) } diff --git a/cmd/collect_github.go b/cmd/collect_github.go index 58d6f8d..deb754f 100644 --- a/cmd/collect_github.go +++ b/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) } diff --git a/cmd/collect_github_release_subcommand.go b/cmd/collect_github_release_subcommand.go index 83565c0..7d7a4fa 100644 --- a/cmd/collect_github_release_subcommand.go +++ b/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") diff --git a/cmd/collect_github_repo.go b/cmd/collect_github_repo.go index d544a90..a8be6ac 100644 --- a/cmd/collect_github_repo.go +++ b/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") diff --git a/cmd/collect_github_repos.go b/cmd/collect_github_repos.go index 71bf451..84ed3fa 100644 --- a/cmd/collect_github_repos.go +++ b/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) } diff --git a/cmd/collect_pwa.go b/cmd/collect_pwa.go index 5c39f09..8275cf0 100644 --- a/cmd/collect_pwa.go +++ b/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") diff --git a/cmd/collect_website.go b/cmd/collect_website.go index 6b67a3b..cfd0b3d 100644 --- a/cmd/collect_website.go +++ b/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") diff --git a/cmd/root.go b/cmd/root.go index 013d430..49c252b 100644 --- a/cmd/root.go +++ b/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") +} diff --git a/cmd/serve.go b/cmd/serve.go index 87e225f..c183ec5 100644 --- a/cmd/serve.go +++ b/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") diff --git a/main.go b/main.go index 7c02e17..b3fadd5 100644 --- a/main.go +++ b/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) diff --git a/pkg/datanode/datanode.go b/pkg/datanode/datanode.go index fe2f43b..9352f3e 100644 --- a/pkg/datanode/datanode.go +++ b/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 { diff --git a/pkg/github/github.go b/pkg/github/github.go index a590205..9ddbf73 100644 --- a/pkg/github/github.go +++ b/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 { diff --git a/pkg/logger/logger.go b/pkg/logger/logger.go index 0dfc2d2..e5021b3 100644 --- a/pkg/logger/logger.go +++ b/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 { diff --git a/pkg/pwa/pwa.go b/pkg/pwa/pwa.go index fc08b36..1f4f947 100644 --- a/pkg/pwa/pwa.go +++ b/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()) diff --git a/pkg/tarfs/tarfs.go b/pkg/tarfs/tarfs.go index 6abbee4..a2a4c2b 100644 --- a/pkg/tarfs/tarfs.go +++ b/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 } diff --git a/pkg/ui/non_interactive_prompter.go b/pkg/ui/non_interactive_prompter.go index 3eb874f..1c9492f 100644 --- a/pkg/ui/non_interactive_prompter.go +++ b/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()) } diff --git a/pkg/ui/progress_writer.go b/pkg/ui/progress_writer.go index b46b51b..11798f5 100644 --- a/pkg/ui/progress_writer.go +++ b/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 } diff --git a/pkg/ui/quote.go b/pkg/ui/quote.go index 3a182cc..ef191f2 100644 --- a/pkg/ui/quote.go +++ b/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 "es, 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 { diff --git a/pkg/website/website.go b/pkg/website/website.go index e98a6b0..64563ee 100644 --- a/pkg/website/website.go +++ b/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 {