feat: add comments and cleanup unused imports across codebase

internal/db/helpers.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 )
 
+// NullStringOr returns n.String if valid and non-empty, otherwise fallback
 func NullStringOr(n sql.NullString, fallback string) string {
 	if n.Valid && n.String != "" {
 		return n.String
@@ -14,6 +15,7 @@ func NullStringOr(n sql.NullString, fallback string) string {
 	return fallback
 }
 
+// DisplayTitle returns the English title, falling back to Japanese then original
 func DisplayTitle(titleEnglish, titleJapanese sql.NullString, titleOriginal string) string {
 	return NullStringOr(titleEnglish, NullStringOr(titleJapanese, titleOriginal))
 }
@@ -22,6 +24,7 @@ func (r GetUserWatchListRow) DisplayTitle() string {
 	return DisplayTitle(r.TitleEnglish, r.TitleJapanese, r.TitleOriginal)
 }
 
+// BoolPtr converts a nullable bool to a pointer; nil if not valid
 func BoolPtr(b sql.NullBool) *bool {
 	if !b.Valid {
 		return nil
@@ -29,6 +32,7 @@ func BoolPtr(b sql.NullBool) *bool {
 	return &b.Bool
 }
 
+// BeginTx starts a transaction and returns the Queries wrapper bound to it
 func BeginTx(ctx context.Context, db *sql.DB) (*Queries, *sql.Tx, error) {
 	if db == nil {
 		return nil, nil, errors.New("database unavailable")

internal/db/migrate.go

@@ -10,6 +10,8 @@ import (
 	"strings"
 )
 
+// RunMigrations applies all *.sql files in migrationsDir in sorted order,
+// skipping any already recorded in migration_version.
 func RunMigrations(db *sql.DB, migrationsDir string) error {
 	if migrationsDir == "" {
 		return fmt.Errorf("migrations directory is required")
@@ -44,22 +46,19 @@ func RunMigrations(db *sql.DB, migrationsDir string) error {
 	for _, migrationFile := range migrations {
 		migrationName := filepath.Base(migrationFile)
 		if migrationApplied(appliedNames, migrationName) {
-			// already applied, skipping silently
-			continue
+			continue // already applied
 		}
 
-		// Read and execute migration
 		migrationSQL, err := os.ReadFile(migrationFile)
 		if err != nil {
 			return err
 		}
 
-		// Strict execution: if it fails, it halts.
 		if _, err := db.Exec(string(migrationSQL)); err != nil {
-			return err
+			return err // stop on first failure
 		}
 
-		// Mark as applied
+		// record applied migration
 		_, err = db.Exec("INSERT INTO migration_version (name) VALUES (?)", migrationName)
 		if err != nil {
 			return err
@@ -97,6 +96,8 @@ func loadAppliedMigrationNames(db *sql.DB) (map[string]struct{}, error) {
 	return applied, nil
 }
 
+// migrationApplied checks the applied names map for a match,
+// including legacy paths and case-insensitive basename matches.
 func migrationApplied(appliedNames map[string]struct{}, migrationName string) bool {
 	if _, exists := appliedNames[migrationName]; exists {
 		return true

internal/db/sqlite.go

@@ -9,6 +9,7 @@ import (
 	_ "github.com/mattn/go-sqlite3"
 )
 
+// Open connects to a sqlite3 database with foreign keys enforced
 func Open(dbFile string) (*sql.DB, error) {
 	db, err := sql.Open("sqlite3", fmt.Sprintf("file:%s?_foreign_keys=on", dbFile))
 	if err != nil {
@@ -17,6 +18,7 @@ func Open(dbFile string) (*sql.DB, error) {
 	return db, nil
 }
 
+// GetDBFile returns the database file path, checking DATABASE_FILE env var first
 func GetDBFile() string {
 	if f := os.Getenv("DATABASE_FILE"); f != "" {
 		return f
@@ -24,6 +26,7 @@ func GetDBFile() string {
 	return "mal.db"
 }
 
+// GetMigrationsDir returns the migrations directory, checking MIGRATIONS_DIR env var first
 func GetMigrationsDir() (string, error) {
 	if dir := os.Getenv("MIGRATIONS_DIR"); dir != "" {
 		return dir, nil
@@ -35,6 +38,7 @@ func GetMigrationsDir() (string, error) {
 	return filepath.Join(wd, "migrations"), nil
 }
 
+// Init opens the database, runs migrations, and returns a Queries instance
 func Init(db *sql.DB) (*Queries, error) {
 	migrationsDir, err := GetMigrationsDir()
 	if err != nil {