pathfinder

pathfinder

Blazingly fast, lightweight CLI to map & track your codebase.

Overview

pathfinder is a command-line tool written in Go that scans a specified directory (and its subdirectories) to count the number of files, directories, and total lines of code.

It is designed to be fast and efficient, leveraging Go's concurrency features to process files in parallel.

It also has a library API that you can use to integrate its functionality into your own Go applications.

Installation

As a CLI Tool:

go install github.com/andrearcaina/pathfinder@latest

As a Go Library:

go get github.com/andrearcaina/pathfinder

Go Example Usage

Here is a simple example of how to use pathfinder as a library in your Go code:

package main

import (
	"fmt"
	"log"

	"github.com/andrearcaina/pathfinder/pkg/pathfinder"
)

func main() {
	fmt.Printf("Supported PathFinder version: %s\n\n", pathfinder.Version())
	fmt.Printf("Supported Languages: %v\n\n", pathfinder.GetSupportedLanguages())

	scanWithConfig()
	scanNoConfig()
}

func scanWithConfig() {
	config := pathfinder.Config{
		PathFlag:       "..",
		RecursiveFlag:  true,
		HiddenFlag:     false,
		DependencyFlag: true,
		BufferSizeFlag: 4,
		MaxDepthFlag:   -1,
	}

	report, err := pathfinder.Scan(&config)
	if err != nil {
		log.Fatalf("Failed to scan codebase: %v", err)
	}

	printReport(report)
}

func scanNoConfig() {
	report, err := pathfinder.Scan(nil)
	if err != nil {
		log.Fatalf("Failed to scan codebase: %v", err)
	}

	printReport(report)
}

func printReport(report pathfinder.CodebaseReport) {
	fmt.Printf("Found %d files across %d languages.\n\n",
		report.CodebaseMetrics.TotalFiles,
		report.CodebaseMetrics.TotalLanguages)

	fmt.Println("Language Breakdown:")
	for _, lang := range report.LanguageMetrics {
		fmt.Printf("• %s: %d lines (%.2f%%)\n",
			lang.Metrics.Language,
			lang.Metrics.Lines,
			lang.Percentage,
		)
	}
}

Output:

Supported PathFinder version: v0.1.3

Supported Languages: [Go JavaScript TypeScript PHP HTML CSS XML Python Java Kotlin C C++ C# Swift JSON YAML Markdown]

Found 21 files across 3 languages.

Language Breakdown:
• JSON: 4859 lines (75.65%)
• Go: 1443 lines (17.67%)
• Markdown: 121 lines (1.32%)
Using default configuration.
Found 1 files across 1 languages.

Language Breakdown:
• Go: 58 lines (81.03%)

CLI Usage

Below I ran pathfinder on this codebase with the -R flag to recursively scan all subdirectories. Image was taken at 2025-08-30 3:08 PM EST.

Then I ran the same command, but instead on my installed Go libraries and packages in WSL to benchmark performance. Image was taken at 2025-08-30 3:08 PM EST.

You can see that it found 73,103 files, 18,219 directories, and 44,858,625 total lines.

> time ./bin/pathfinder ../../../go/ -R

# time output (as of 2025-08-30 3:08 PM EST)
./bin/pathfinder -p ../../../go/ -R  5.88s user 8.15s system 281% cpu 4.995 total

This only took 4.995 seconds (on my machine), utilizing 281% of the CPU. This is because pathfinder uses goroutines for concurrent file reading and processing.

I then ran it again on the same directory:

> time ./bin/pathfinder ../../../go/ -R

...

# time output (as of 2025-08-30 3:08 PM EST)
./bin/pathfinder -p ../../../go/ -R  4.69s user 2.97s system 686% cpu 1.117 total

This time it took only 1.117 seconds to run, utilizing 665% of the CPU. The second run is much faster because the OS caches file data in memory, reducing I/O overhead and allowing goroutines to utilize more cores efficiently.