release notes for "debug" log level

CHANGELOG.md

@@ -18,6 +18,44 @@
 
     The fix is to track all re-exports in the import chain from the original file to the file containing the final symbol and then retain all of those statements if the import ends up being used.
 
+* Add a very verbose `debug` log level
+
+    This log level is an experiment. Enabling it logs a lot of information (currently only about path resolution). The idea is that if you are having an obscure issue, the debug log level might contain some useful information. Unlike normal logs which are meant to mainly provide actionable information, these debug logs are intentionally mostly noise and are designed to be searched through instead.
+
+    Here is an example of debug-level log output:
+
+    ```
+     > debug: Resolving import "react" in directory "src" of type "import-statement"
+       note: Read 26 entries for directory "src"
+       note: Searching for "react" in "node_modules" directories starting from "src"
+       note: Attempting to load "src/react" as a file
+       note: Failed to find file "src/react"
+       note: Failed to find file "src/react.tsx"
+       note: Failed to find file "src/react.ts"
+       note: Failed to find file "src/react.js"
+       note: Failed to find file "src/react.css"
+       note: Failed to find file "src/react.svg"
+       note: Attempting to load "src/react" as a directory
+       note: Failed to read directory "src/react"
+       note: Parsed package name "react" and package subpath "."
+       note: Checking for a package in the directory "node_modules/react"
+       note: Read 7 entries for directory "node_modules/react"
+       note: Read 393 entries for directory "node_modules"
+       note: Attempting to load "node_modules/react" as a file
+       note: Failed to find file "node_modules/react"
+       note: Failed to find file "node_modules/react.tsx"
+       note: Failed to find file "node_modules/react.ts"
+       note: Failed to find file "node_modules/react.js"
+       note: Failed to find file "node_modules/react.css"
+       note: Failed to find file "node_modules/react.svg"
+       note: Attempting to load "node_modules/react" as a directory
+       note: Read 7 entries for directory "node_modules/react"
+       note: Resolved to "node_modules/react/index.js" using the "main" field in "node_modules/react/package.json"
+       note: Read 7 entries for directory "node_modules/react"
+       note: Read 7 entries for directory "node_modules/react"
+       note: Primary path is "node_modules/react/index.js" in namespace "file"
+    ```
+
 ## 0.11.2
 
 * Fix missing symbol dependency for wrapped ESM files ([#1086](https://github.com/evanw/esbuild/issues/1086))

internal/bundler/bundler.go

@@ -604,7 +604,10 @@ func extractSourceMapFromComment(
 	if absResolveDir != "" {
 		absPath := fs.Join(absResolveDir, comment.Text)
 		path := logger.Path{Text: absPath, Namespace: "file"}
-		contents, err := fsCache.ReadFile(fs, absPath)
+		contents, err, originalError := fsCache.ReadFile(fs, absPath)
+		if log.Debug && originalError != nil {
+			log.AddDebug(nil, logger.Loc{}, fmt.Sprintf("Failed to read file %q: %s", absPath, originalError.Error()))
+		}
 		if err != nil {
 			if err == syscall.ENOENT {
 				// Don't report a warning because this is likely unactionable
@@ -890,20 +893,25 @@ func runOnLoadPlugins(
 
 	// Read normal modules from disk
 	if source.KeyPath.Namespace == "file" {
-		if contents, err := fsCache.ReadFile(fs, source.KeyPath.Text); err == nil {
+		if contents, err, originalError := fsCache.ReadFile(fs, source.KeyPath.Text); err == nil {
 			source.Contents = contents
 			return loaderPluginResult{
 				loader:        config.LoaderDefault,
 				absResolveDir: fs.Dir(source.KeyPath.Text),
 			}, true
-		} else if err == syscall.ENOENT {
-			log.AddRangeError(importSource, importPathRange,
-				fmt.Sprintf("Could not read from file: %s", source.KeyPath.Text))
-			return loaderPluginResult{}, false
 		} else {
-			log.AddRangeError(importSource, importPathRange,
-				fmt.Sprintf("Cannot read file %q: %s", res.PrettyPath(source.KeyPath), err.Error()))
-			return loaderPluginResult{}, false
+			if log.Debug && originalError != nil {
+				log.AddDebug(nil, logger.Loc{}, fmt.Sprintf("Failed to read file %q: %s", source.KeyPath.Text, originalError.Error()))
+			}
+			if err == syscall.ENOENT {
+				log.AddRangeError(importSource, importPathRange,
+					fmt.Sprintf("Could not read from file: %s", source.KeyPath.Text))
+				return loaderPluginResult{}, false
+			} else {
+				log.AddRangeError(importSource, importPathRange,
+					fmt.Sprintf("Cannot read file %q: %s", res.PrettyPath(source.KeyPath), err.Error()))
+				return loaderPluginResult{}, false
+			}
 		}
 	}
 
@@ -995,7 +1003,7 @@ func ScanBundle(
 ) Bundle {
 	start := time.Now()
 	if log.Debug {
-		log.AddDebug(nil, logger.Loc{}, "Started scan phase")
+		log.AddDebug(nil, logger.Loc{}, "Started the scan phase")
 	}
 
 	applyOptionDefaults(&options)
@@ -1025,7 +1033,7 @@ func ScanBundle(
 	files := s.processScannedFiles()
 
 	if log.Debug {
-		log.AddDebug(nil, logger.Loc{}, fmt.Sprintf("Ended scan phase (%dms)", time.Since(start).Milliseconds()))
+		log.AddDebug(nil, logger.Loc{}, fmt.Sprintf("Ended the scan phase (%dms)", time.Since(start).Milliseconds()))
 	}
 
 	return Bundle{
@@ -1290,7 +1298,7 @@ func (s *scanner) addEntryPoints(entryPoints []EntryPoint) []entryMeta {
 		}
 		dir := s.fs.Dir(absPath)
 		base := s.fs.Base(absPath)
-		if entries, err := s.fs.ReadDirectory(dir); err == nil {
+		if entries, err, originalError := s.fs.ReadDirectory(dir); err == nil {
 			if entry, _ := entries.Get(base); entry != nil && entry.Kind(s.fs) == fs.FileEntry {
 				entryPoint.IsFile = true
 
@@ -1310,6 +1318,8 @@ func (s *scanner) addEntryPoints(entryPoints []EntryPoint) []entryMeta {
 					entryPoint.InputPath = "./" + entryPoint.InputPath
 				}
 			}
+		} else if s.log.Debug && originalError != nil {
+			s.log.AddDebug(nil, logger.Loc{}, fmt.Sprintf("Failed to read directory %q: %s", absPath, originalError.Error()))
 		}
 	}
 
@@ -1881,7 +1891,7 @@ func applyOptionDefaults(options *config.Options) {
 func (b *Bundle) Compile(log logger.Log, options config.Options) ([]OutputFile, string) {
 	start := time.Now()
 	if log.Debug {
-		log.AddDebug(nil, logger.Loc{}, "Started compile phase")
+		log.AddDebug(nil, logger.Loc{}, "Started the compile phase")
 	}
 
 	applyOptionDefaults(&options)
@@ -1984,7 +1994,7 @@ func (b *Bundle) Compile(log logger.Log, options config.Options) ([]OutputFile,
 	}
 
 	if log.Debug {
-		log.AddDebug(nil, logger.Loc{}, fmt.Sprintf("Ended compile phase (%dms)", time.Since(start).Milliseconds()))
+		log.AddDebug(nil, logger.Loc{}, fmt.Sprintf("Ended the compile phase (%dms)", time.Since(start).Milliseconds()))
 	}
 
 	return outputFiles, metafileJSON

internal/cache/cache_fs.go

@@ -22,7 +22,7 @@ type fsEntry struct {
 	isModKeyUsable bool
 }
 
-func (c *FSCache) ReadFile(fs fs.FS, path string) (string, error) {
+func (c *FSCache) ReadFile(fs fs.FS, path string) (contents string, canonicalError error, originalError error) {
 	entry := func() *fsEntry {
 		c.mutex.Lock()
 		defer c.mutex.Unlock()
@@ -33,12 +33,12 @@ func (c *FSCache) ReadFile(fs fs.FS, path string) (string, error) {
 	// the contents of the file are also the same and skip reading the file.
 	modKey, modKeyErr := fs.ModKey(path)
 	if entry != nil && entry.isModKeyUsable && modKeyErr == nil && entry.modKey == modKey {
-		return entry.contents, nil
+		return entry.contents, nil, nil
 	}
 
-	contents, err := fs.ReadFile(path)
+	contents, err, originalError := fs.ReadFile(path)
 	if err != nil {
-		return "", err
+		return "", err, originalError
 	}
 
 	c.mutex.Lock()
@@ -48,5 +48,5 @@ func (c *FSCache) ReadFile(fs fs.FS, path string) (string, error) {
 		modKey:         modKey,
 		isModKeyUsable: modKeyErr == nil,
 	}
-	return contents, nil
+	return contents, nil, nil
 }

internal/fs/fs.go

@@ -90,8 +90,8 @@ func (entries DirEntries) UnorderedKeys() (keys []string) {
 type FS interface {
 	// The returned map is immutable and is cached across invocations. Do not
 	// mutate it.
-	ReadDirectory(path string) (DirEntries, error)
-	ReadFile(path string) (string, error)
+	ReadDirectory(path string) (entries DirEntries, canonicalError error, originalError error)
+	ReadFile(path string) (contents string, canonicalError error, originalError error)
 
 	// This is a key made from the information returned by "stat". It is intended
 	// to be different if the file has been edited, and to otherwise be equal if

internal/fs/fs_mock.go

@@ -48,19 +48,18 @@ func MockFS(input map[string]string) FS {
 	return &mockFS{dirs, files}
 }
 
-func (fs *mockFS) ReadDirectory(path string) (DirEntries, error) {
+func (fs *mockFS) ReadDirectory(path string) (DirEntries, error, error) {
 	if dir, ok := fs.dirs[path]; ok {
-		return dir, nil
+		return dir, nil, nil
 	}
-	return DirEntries{}, syscall.ENOENT
+	return DirEntries{}, syscall.ENOENT, syscall.ENOENT
 }
 
-func (fs *mockFS) ReadFile(path string) (string, error) {
-	contents, ok := fs.files[path]
-	if !ok {
-		return "", syscall.ENOENT
+func (fs *mockFS) ReadFile(path string) (string, error, error) {
+	if contents, ok := fs.files[path]; ok {
+		return contents, nil, nil
 	}
-	return contents, nil
+	return "", syscall.ENOENT, syscall.ENOENT
 }
 
 func (fs *mockFS) ModKey(path string) (ModKey, error) {

internal/fs/fs_mock_test.go

@@ -14,13 +14,13 @@ func TestMockFSBasic(t *testing.T) {
 	})
 
 	// Test a missing file
-	_, err := fs.ReadFile("/missing.txt")
+	_, err, _ := fs.ReadFile("/missing.txt")
 	if err == nil {
 		t.Fatal("Unexpectedly found /missing.txt")
 	}
 
 	// Test an existing file
-	readme, err := fs.ReadFile("/README.md")
+	readme, err, _ := fs.ReadFile("/README.md")
 	if err != nil {
 		t.Fatal("Expected to find /README.md")
 	}
@@ -29,7 +29,7 @@ func TestMockFSBasic(t *testing.T) {
 	}
 
 	// Test an existing nested file
-	index, err := fs.ReadFile("/src/index.js")
+	index, err, _ := fs.ReadFile("/src/index.js")
 	if err != nil {
 		t.Fatal("Expected to find /src/index.js")
 	}
@@ -38,13 +38,13 @@ func TestMockFSBasic(t *testing.T) {
 	}
 
 	// Test a missing directory
-	_, err = fs.ReadDirectory("/missing")
+	_, err, _ = fs.ReadDirectory("/missing")
 	if err == nil {
 		t.Fatal("Unexpectedly found /missing")
 	}
 
 	// Test a nested directory
-	src, err := fs.ReadDirectory("/src")
+	src, err, _ := fs.ReadDirectory("/src")
 	if err != nil {
 		t.Fatal("Expected to find /src")
 	}
@@ -57,7 +57,7 @@ func TestMockFSBasic(t *testing.T) {
 	}
 
 	// Test the top-level directory
-	slash, err := fs.ReadDirectory("/")
+	slash, err, _ := fs.ReadDirectory("/")
 	if err != nil {
 		t.Fatal("Expected to find /")
 	}