Add brief diff subcommand

Filters the toolchain report to only show tools, languages, and
configuration relevant to files changed between git refs. Defaults to
comparing against the default branch with uncommitted changes included.

Author: andrew

README.md

@@ -12,10 +12,11 @@ Add this to your `CLAUDE.md`, `agents.md`, or equivalent agent instructions file
 
 ```
 Before starting work on this project, run `brief .` to understand the toolchain,
-test commands, linters, and project conventions.
+test commands, linters, and project conventions. If on a branch, also run
+`brief diff` to see which parts of the toolchain are affected by your changes.
 ```
 
-The agent will get back structured information about the project's language, package manager, test runner, linter, formatter, build tools, and more, so it doesn't have to guess or ask you.
+The agent will get back structured information about the project's language, package manager, test runner, linter, formatter, build tools, and more, so it doesn't have to guess or ask you. On a feature branch, `brief diff` narrows that down to just the tools relevant to what's been changed, so the agent knows which linters to run, which test frameworks matter, and which config files are in play.
 
 To let Claude Code run `brief` without prompting for approval each time, add this to `~/.claude/settings.json`:
 
@@ -39,6 +40,7 @@ Or download a binary from [releases](https://github.com/git-pkgs/brief/releases)
 
 ```
 brief [flags] [path | url]        Detect project toolchain
+brief diff [flags] [ref1] [ref2]  Detect only what changed between refs
 brief enrich [flags] [path]       Detect and enrich with external data
 brief list tools                  All tools in the knowledge base
 brief list ecosystems             Supported ecosystems
@@ -94,6 +96,20 @@ Lines:       22912 code  191 files (scc)
 
 Use `--verbose` to include homepage, docs, and repo links for each detected tool.
 
+## Diff
+
+`brief diff` runs the same detection but filters the report to only show tools, languages, and configuration relevant to files that changed. Useful for understanding what a branch or PR touches in terms of toolchain.
+
+```
+brief diff                        Compare against default branch + uncommitted
+brief diff main                   Compare main to HEAD + uncommitted
+brief diff v1.0.0 v2.0.0         Compare between two refs
+```
+
+With no arguments it auto-detects the default branch from `origin/HEAD`, falling back to `main` or `master`. The output lists changed files and only the toolchain entries those files relate to: if you changed a `.go` file, you'll see Go and its tools but not Python. If you changed `.golangci.yml`, you'll see golangci-lint. If you changed `go.mod`, you'll see dependency information.
+
+Same output format as `brief` -- JSON when piped, human-readable on a TTY.
+
 ## Enrichment
 
 `brief enrich` runs the same scan, then fetches metadata from external APIs about the project itself: what packages it publishes, their download counts and dependents, runtime end-of-life status, and OpenSSF Scorecard.

brief.go

@@ -160,6 +160,8 @@ type RuntimeEOL struct {
 type Report struct {
 	Version         string                 `json:"version"`
 	Path            string                 `json:"path"`
+	DiffRef         string                 `json:"diff_ref,omitempty"`
+	ChangedFiles    []string               `json:"changed_files,omitempty"`
 	Languages       []Detection            `json:"languages"`
 	PackageManagers []Detection            `json:"package_managers"`
 	Scripts         []Script               `json:"scripts,omitempty"`

cmd/brief/diff.go

@@ -0,0 +1,218 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+
+	"github.com/git-pkgs/brief"
+	"github.com/git-pkgs/brief/detect"
+	"github.com/git-pkgs/brief/kb"
+	"github.com/git-pkgs/brief/report"
+)
+
+func cmdDiff(args []string) {
+	fs := flag.NewFlagSet("brief diff", flag.ExitOnError)
+	jsonFlag := fs.Bool("json", false, "Force JSON output")
+	humanFlag := fs.Bool("human", false, "Force human-readable output")
+	verbose := fs.Bool("verbose", false, "Include breadcrumb/reference information")
+	category := fs.String("category", "", "Only report on specific category")
+	_ = fs.Parse(args)
+
+	// Determine the project root (git toplevel).
+	root, err := gitToplevel()
+	if err != nil {
+		_, _ = fmt.Fprintf(os.Stderr, "error: not a git repository\n")
+		os.Exit(1)
+	}
+
+	// Determine diff refs.
+	// No args: diff from default branch to working tree (including uncommitted).
+	// One arg: diff from that ref to working tree.
+	// Two args: diff between two refs.
+	var ref1, ref2 string
+	var diffRef string
+	includeUncommitted := false
+
+	switch fs.NArg() {
+	case 0:
+		// Default: compare against the default branch + uncommitted changes.
+		ref1 = detectDefaultBranch(root)
+		includeUncommitted = true
+		diffRef = ref1 + "..HEAD (+ uncommitted)"
+	case 1:
+		ref1 = fs.Arg(0)
+		includeUncommitted = true
+		diffRef = ref1 + " (+ uncommitted)"
+	case 2:
+		ref1 = fs.Arg(0)
+		ref2 = fs.Arg(1)
+		diffRef = ref1 + ".." + ref2
+	default:
+		_, _ = fmt.Fprintf(os.Stderr, "usage: brief diff [ref1] [ref2]\n")
+		os.Exit(1)
+	}
+
+	changedFiles, err := gitChangedFiles(context.Background(), root, ref1, ref2, includeUncommitted)
+	if err != nil {
+		_, _ = fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		os.Exit(1)
+	}
+
+	if len(changedFiles) == 0 {
+		_, _ = fmt.Fprintf(os.Stderr, "no changed files\n")
+		os.Exit(0)
+	}
+
+	knowledgeBase, err := kb.Load(brief.KnowledgeFS)
+	if err != nil {
+		_, _ = fmt.Fprintf(os.Stderr, "error loading knowledge base: %v\n", err)
+		os.Exit(1)
+	}
+
+	engine := detect.New(knowledgeBase, root)
+	r, err := engine.Run()
+	if err != nil {
+		_, _ = fmt.Fprintf(os.Stderr, "error: %v\n", err)
+		os.Exit(1)
+	}
+
+	r.DiffRef = diffRef
+	r.ChangedFiles = changedFiles
+
+	r = detect.FilterByChangedFiles(r, knowledgeBase, changedFiles)
+
+	if *category != "" {
+		r = filterCategory(r, *category)
+	}
+
+	useJSON := *jsonFlag || (!*humanFlag && !isTTY())
+
+	if useJSON {
+		if err := report.JSON(os.Stdout, r); err != nil {
+			_, _ = fmt.Fprintf(os.Stderr, "error writing JSON: %v\n", err)
+			os.Exit(1)
+		}
+	} else {
+		report.Human(os.Stdout, r, *verbose)
+	}
+}
+
+// gitToplevel returns the root of the git repository.
+func gitToplevel() (string, error) {
+	cmd := exec.Command("git", "rev-parse", "--show-toplevel")
+	out, err := cmd.Output()
+	if err != nil {
+		return "", err
+	}
+	return strings.TrimSpace(string(out)), nil
+}
+
+// detectDefaultBranch tries to find the default branch name (main or master).
+func detectDefaultBranch(root string) string {
+	cmd := exec.Command("git", "rev-parse", "--abbrev-ref", "origin/HEAD")
+	cmd.Dir = root
+	if out, err := cmd.Output(); err == nil {
+		ref := strings.TrimSpace(string(out))
+		if after, ok := strings.CutPrefix(ref, "origin/"); ok && after != "" {
+			return after
+		}
+	}
+
+	// Fall back to checking if main or master exists.
+	for _, branch := range []string{"main", "master"} {
+		cmd := exec.Command("git", "rev-parse", "--verify", branch)
+		cmd.Dir = root
+		if err := cmd.Run(); err == nil {
+			return branch
+		}
+	}
+
+	return "main"
+}
+
+// gitChangedFiles returns the list of files that differ between refs.
+// If includeUncommitted is true, also includes staged and unstaged changes.
+func gitChangedFiles(ctx context.Context, root, ref1, ref2 string, includeUncommitted bool) ([]string, error) {
+	seen := make(map[string]bool)
+	var files []string
+
+	addFiles := func(output string) {
+		for _, f := range strings.Split(strings.TrimSpace(output), "\n") {
+			f = strings.TrimSpace(f)
+			if f != "" && !seen[f] {
+				seen[f] = true
+				files = append(files, f)
+			}
+		}
+	}
+
+	if ref2 != "" {
+		// Two-ref diff: just diff between the two.
+		cmd := exec.CommandContext(ctx, "git", "diff", "--name-only", ref1+"..."+ref2)
+		cmd.Dir = root
+		out, err := cmd.Output()
+		if err != nil {
+			// Try two-dot diff if three-dot fails.
+			cmd = exec.CommandContext(ctx, "git", "diff", "--name-only", ref1, ref2)
+			cmd.Dir = root
+			out, err = cmd.Output()
+			if err != nil {
+				return nil, fmt.Errorf("git diff %s %s: %w", ref1, ref2, err)
+			}
+		}
+		addFiles(string(out))
+	} else {
+		// Compare ref1 to HEAD.
+		cmd := exec.CommandContext(ctx, "git", "diff", "--name-only", ref1+"...HEAD")
+		cmd.Dir = root
+		out, err := cmd.Output()
+		if err != nil {
+			cmd = exec.CommandContext(ctx, "git", "diff", "--name-only", ref1, "HEAD")
+			cmd.Dir = root
+			out, err = cmd.Output()
+			if err != nil {
+				return nil, fmt.Errorf("git diff %s: %w", ref1, err)
+			}
+		}
+		addFiles(string(out))
+
+		if includeUncommitted {
+			// Staged changes.
+			cmd = exec.CommandContext(ctx, "git", "diff", "--name-only", "--cached")
+			cmd.Dir = root
+			if out, err := cmd.Output(); err == nil {
+				addFiles(string(out))
+			}
+
+			// Unstaged changes.
+			cmd = exec.CommandContext(ctx, "git", "diff", "--name-only")
+			cmd.Dir = root
+			if out, err := cmd.Output(); err == nil {
+				addFiles(string(out))
+			}
+
+			// Untracked files.
+			cmd = exec.CommandContext(ctx, "git", "ls-files", "--others", "--exclude-standard")
+			cmd.Dir = root
+			if out, err := cmd.Output(); err == nil {
+				addFiles(string(out))
+			}
+		}
+	}
+
+	// Make paths relative to root.
+	for i, f := range files {
+		if filepath.IsAbs(f) {
+			if rel, err := filepath.Rel(root, f); err == nil {
+				files[i] = rel
+			}
+		}
+	}
+
+	return files, nil
+}

cmd/brief/main.go

@@ -33,6 +33,9 @@ func main() {
 		case "enrich":
 			cmdEnrich(os.Args[2:])
 			return
+		case "diff":
+			cmdDiff(os.Args[2:])
+			return
 		}
 	}