blast_radius.go

package main

import (
	"bytes"
	"context"
	"encoding/json"
	"errors"
	"flag"
	"fmt"
	"io"
	"os"
	"path"
	"path/filepath"
	"regexp"
	"sort"
	"strconv"
	"strings"
	"unicode/utf8"

	"codemap/analysis"
	"codemap/cmd"
	"codemap/config"
	"codemap/render"
	"codemap/scanner"
)

type blastRadiusFormat string

const (
	blastRadiusFormatMarkdown blastRadiusFormat = "markdown"
	blastRadiusFormatText     blastRadiusFormat = "text"
	blastRadiusFormatJSON     blastRadiusFormat = "json"
)

var ansiSequencePattern = regexp.MustCompile(`\x1b\[[0-9;]*[A-Za-z]`)

type blastRadiusLimits struct {
	MaxTotalChars         int `json:"max_total_chars"`
	MaxChangedFiles       int `json:"max_changed_files"`
	MaxAffected           int `json:"max_affected"`
	MaxContext            int `json:"max_context"`
	MaxSnippets           int `json:"max_snippets"`
	MaxSnippetsPerChanged int `json:"max_snippets_per_changed"`
	SnippetRadius         int `json:"snippet_radius"`
	MaxSnippetChars       int `json:"max_snippet_chars"`
	MaxDiffChars          int `json:"max_diff_chars"`
	MaxDepsChars          int `json:"max_deps_chars"`
	MaxImportersChars     int `json:"max_importers_chars"`
	MaxImporterFiles      int `json:"max_importer_files"`
	MaxImportersPerFile   int `json:"max_importers_per_file"`
}

type blastRadiusDiff struct {
	Root              string               `json:"root"`
	Name              string               `json:"name,omitempty"`
	Mode              string               `json:"mode"`
	Files             []scanner.FileInfo   `json:"files"`
	DiffRef           string               `json:"diff_ref,omitempty"`
	Impact            []scanner.ImpactInfo `json:"impact,omitempty"`
	Depth             int                  `json:"depth,omitempty"`
	Only              []string             `json:"only,omitempty"`
	Exclude           []string             `json:"exclude,omitempty"`
	ChangedFilesTotal int                  `json:"changed_files_total"`
	DiffTotals        *scanner.DiffTotals  `json:"diff_totals,omitempty"`
}

type blastRadiusDeps struct {
	Root              string                 `json:"root"`
	Mode              string                 `json:"mode"`
	Files             []scanner.FileAnalysis `json:"files"`
	ExternalDeps      map[string][]string    `json:"external_deps"`
	DiffRef           string                 `json:"diff_ref,omitempty"`
	ChangedFilesTotal int                    `json:"changed_files_total"`
	CoverageStatus    string                 `json:"coverage_status,omitempty"`
	CoverageNotes     []string               `json:"coverage_notes,omitempty"`
}

type blastRadiusImporters struct {
	Root            string   `json:"root"`
	Mode            string   `json:"mode"`
	File            string   `json:"file"`
	Importers       []string `json:"importers"`
	Imports         []string `json:"imports,omitempty"`
	HubImports      []string `json:"hub_imports,omitempty"`
	ImporterCount   int      `json:"importer_count"`
	IsHub           bool     `json:"is_hub"`
	ImportersTotal  int      `json:"importers_total"`
	ImportsTotal    int      `json:"imports_total"`
	HubImportsTotal int      `json:"hub_imports_total"`
	CoverageStatus  string   `json:"coverage_status,omitempty"`
	CoverageNotes   []string `json:"coverage_notes,omitempty"`
}

type blastRadiusHighest struct {
	File          string `json:"file"`
	ImporterCount int    `json:"importer_count"`
}

type blastRadiusSummary struct {
	ChangedFiles                      int                 `json:"changed_files"`
	ChangedFilesTotal                 int                 `json:"changed_files_total"`
	FilesWithDependents               int                 `json:"files_with_dependents"`
	ImpactedOutsideDiffTotal          int                 `json:"impacted_outside_diff_total"`
	ImpactedOutsideDiffShown          int                 `json:"impacted_outside_diff_shown"`
	DependencyContextOutsideDiffTotal int                 `json:"dependency_context_outside_diff_total"`
	DependencyContextOutsideDiffShown int                 `json:"dependency_context_outside_diff_shown"`
	MaxDirectDependents               int                 `json:"max_direct_dependents"`
	HighestBlastRadius                *blastRadiusHighest `json:"highest_blast_radius,omitempty"`
}

type blastRadiusRelation struct {
	Path             string `json:"path"`
	Via              string `json:"via"`
	Relation         string `json:"relation"`
	ViaIsHub         bool   `json:"via_is_hub,omitempty"`
	ViaImporterCount int    `json:"via_importer_count,omitempty"`
	IsHub            bool   `json:"is_hub,omitempty"`
}

type blastRadiusSnippet struct {
	Category    string `json:"category"`
	Path        string `json:"path"`
	Via         string `json:"via"`
	Reason      string `json:"reason"`
	MatchedTerm string `json:"matched_term"`
	MatchKind   string `json:"match_kind"`
	Language    string `json:"language"`
	Excerpt     string `json:"excerpt"`
}

type blastRadiusRenderedImporter struct {
	File string `json:"file"`
	Text string `json:"text"`
}

type blastRadiusRendered struct {
	Diff               string                        `json:"diff"`
	Deps               string                        `json:"deps"`
	Importers          []blastRadiusRenderedImporter `json:"importers"`
	ImportersTruncated bool                          `json:"importers_truncated,omitempty"`
}

type blastRadiusBundle struct {
	Root                         string                    `json:"root"`
	Ref                          string                    `json:"ref"`
	Summary                      blastRadiusSummary        `json:"summary"`
	Diff                         blastRadiusDiff           `json:"diff"`
	Deps                         blastRadiusDeps           `json:"deps"`
	Importers                    []blastRadiusImporters    `json:"importers"`
	Limits                       blastRadiusLimits         `json:"limits"`
	ImpactedOutsideDiff          []blastRadiusRelation     `json:"impacted_outside_diff"`
	DependencyContextOutsideDiff []blastRadiusRelation     `json:"dependency_context_outside_diff"`
	AffectedModules              []blastRadiusModuleImpact `json:"affected_modules,omitempty"`
	Snippets                     []blastRadiusSnippet      `json:"snippets"`
	Rendered                     blastRadiusRendered       `json:"rendered"`
}

type blastChangedMeta struct {
	Functions []string
	Stem      string
	Dir       string
	DirBase   string
	PathNoExt string
}

type blastOutputBuilder struct {
	total     int
	remaining int
	builder   strings.Builder
}

func runBlastRadiusSubcommand(args []string) {
	if code := executeBlastRadiusSubcommand(args); code != 0 {
		os.Exit(code)
	}
}

func executeBlastRadiusSubcommand(args []string) int {
	limits := defaultBlastRadiusLimits()
	fs := flag.NewFlagSet("blast-radius", flag.ContinueOnError)
	fs.SetOutput(os.Stderr)

	// Format flags resolve last-wins: passing more than one simply uses the
	// last one on the command line (matching the original shell wrapper).
	format := blastRadiusFormatMarkdown
	chooseFormat := func(f blastRadiusFormat) func(string) error {
		return func(string) error {
			format = f
			return nil
		}
	}
	var help bool
	ref := fs.String("ref", "main", "Branch/ref to compare against")
	fs.BoolFunc("json", "Emit a single JSON object", chooseFormat(blastRadiusFormatJSON))
	fs.BoolFunc("markdown", "Emit Markdown output", chooseFormat(blastRadiusFormatMarkdown))
	fs.BoolFunc("md", "Emit Markdown output", chooseFormat(blastRadiusFormatMarkdown))
	fs.BoolFunc("text", "Emit plain text output", chooseFormat(blastRadiusFormatText))
	fs.BoolVar(&help, "help", false, "Show blast-radius help")
	fs.BoolVar(&help, "h", false, "Show blast-radius help")
	fs.IntVar(&limits.MaxTotalChars, "max-total-chars", limits.MaxTotalChars, "Hard cap for markdown/text output")
	fs.IntVar(&limits.MaxChangedFiles, "max-changed-files", limits.MaxChangedFiles, "Maximum changed files to include")
	fs.IntVar(&limits.MaxAffected, "max-affected", limits.MaxAffected, "Maximum affected files outside diff")
	fs.IntVar(&limits.MaxContext, "max-context", limits.MaxContext, "Maximum dependency context entries outside diff")
	fs.IntVar(&limits.MaxSnippets, "max-snippets", limits.MaxSnippets, "Maximum impact snippets")
	fs.IntVar(&limits.MaxSnippetsPerChanged, "max-snippets-per-changed", limits.MaxSnippetsPerChanged, "Maximum snippets per changed file")
	fs.IntVar(&limits.SnippetRadius, "snippet-radius", limits.SnippetRadius, "Lines of context around each snippet match")
	fs.IntVar(&limits.MaxSnippetChars, "max-snippet-chars", limits.MaxSnippetChars, "Maximum characters per snippet")
	fs.IntVar(&limits.MaxDiffChars, "max-diff-chars", limits.MaxDiffChars, "Maximum diff section characters")
	fs.IntVar(&limits.MaxDepsChars, "max-deps-chars", limits.MaxDepsChars, "Maximum dependency section characters")
	fs.IntVar(&limits.MaxImportersChars, "max-importers-chars", limits.MaxImportersChars, "Maximum importer section characters")
	fs.IntVar(&limits.MaxImporterFiles, "max-importer-files", limits.MaxImporterFiles, "Maximum changed files to render importer sections for")
	fs.IntVar(&limits.MaxImportersPerFile, "max-importers-per-file", limits.MaxImportersPerFile, "Maximum importer/import list entries per file in JSON")
	fs.Usage = func() {
		printBlastRadiusUsage(fs)
	}

	root, err := parseBlastRadiusArgs(fs, args)
	if err != nil {
		if errors.Is(err, flag.ErrHelp) {
			return 0
		}
		return 2
	}

	if help {
		fs.Usage()
		return 0
	}

	limits = clampBlastRadiusLimits(limits)
	absRoot, cleanup, err := resolveBlastRadiusRoot(root)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error preparing root: %v\n", err)
		return 1
	}
	defer cleanup()
	if _, err := cmd.ValidateProjectPath(absRoot); err != nil {
		fmt.Fprintf(os.Stderr, "Error preparing root: %v\n", err)
		return 1
	}

	bundle, err := buildBlastRadiusBundle(absRoot, *ref, limits)
	if err != nil {
		var diffErr *blastRadiusDiffError
		switch {
		case errors.Is(err, scanner.ErrAstGrepNotFound):
			printAstGrepInstallHint(os.Stderr, err)
		case errors.As(err, &diffErr):
			fmt.Fprintf(os.Stderr, "Error building blast radius: %v\n", err)
			fmt.Fprintf(os.Stderr, "Make sure '%s' is a valid branch/ref\n", diffErr.ref)
		default:
			fmt.Fprintf(os.Stderr, "Error building blast radius: %v\n", err)
		}
		return 1
	}

	switch format {
	case blastRadiusFormatJSON:
		enc := json.NewEncoder(os.Stdout)
		enc.SetIndent("", "  ")
		_ = enc.Encode(bundle)
	case blastRadiusFormatText:
		fmt.Print(renderBlastRadiusText(bundle))
	default:
		fmt.Print(renderBlastRadiusMarkdown(bundle))
	}
	return 0
}

func printBlastRadiusUsage(fs *flag.FlagSet) {
	out := fs.Output()
	if out == nil {
		out = os.Stderr
	}

	fmt.Fprintln(out, "codemap blast-radius - Build a compact, bounded blast-radius bundle")
	fmt.Fprintln(out)
	fmt.Fprintln(out, "Usage:")
	fmt.Fprintln(out, "  codemap blast-radius [--json|--markdown|--text] [--ref <base-ref>] [path]")
	fmt.Fprintln(out)
	fmt.Fprintln(out, "Examples:")
	fmt.Fprintln(out, "  codemap blast-radius --ref main .")
	fmt.Fprintln(out, "  codemap blast-radius --json --ref develop /path/to/repo")
	fmt.Fprintln(out)
	fmt.Fprintln(out, "Flags:")
	fs.PrintDefaults()
	fmt.Fprintln(out)
	fmt.Fprintln(out, "Environment overrides:")
	fmt.Fprintln(out, "  CODEMAP_BLAST_MAX_TOTAL_CHARS")
	fmt.Fprintln(out, "  CODEMAP_BLAST_MAX_CHANGED_FILES")
	fmt.Fprintln(out, "  CODEMAP_BLAST_MAX_AFFECTED")
	fmt.Fprintln(out, "  CODEMAP_BLAST_MAX_CONTEXT")
	fmt.Fprintln(out, "  CODEMAP_BLAST_MAX_SNIPPETS")
	fmt.Fprintln(out, "  CODEMAP_BLAST_MAX_SNIPPETS_PER_CHANGED")
	fmt.Fprintln(out, "  CODEMAP_BLAST_SNIPPET_RADIUS")
	fmt.Fprintln(out, "  CODEMAP_BLAST_MAX_SNIPPET_CHARS")
	fmt.Fprintln(out, "  CODEMAP_BLAST_MAX_DIFF_CHARS")
	fmt.Fprintln(out, "  CODEMAP_BLAST_MAX_DEPS_CHARS")
	fmt.Fprintln(out, "  CODEMAP_BLAST_MAX_IMPORTERS_CHARS")
	fmt.Fprintln(out, "  CODEMAP_BLAST_MAX_IMPORTER_FILES")
	fmt.Fprintln(out, "  CODEMAP_BLAST_MAX_IMPORTERS_PER_FILE")
}

// parseBlastRadiusArgs parses flags that may appear before or after the single
// optional positional path. Go's flag package stops at the first non-flag
// argument, so we re-parse the remainder after each positional to support
// position-independent flags (e.g. `blast-radius . --json`).
func parseBlastRadiusArgs(fs *flag.FlagSet, args []string) (string, error) {
	var positionals []string
	rest := args
	for {
		if err := fs.Parse(rest); err != nil {
			return "", err
		}
		if fs.NArg() == 0 {
			break
		}
		positionals = append(positionals, fs.Arg(0))
		rest = fs.Args()[1:]
	}
	if len(positionals) > 1 {
		fmt.Fprintln(os.Stderr, "Usage: codemap blast-radius [--json|--markdown|--text] [--ref <base-ref>] [path]")
		return "", fmt.Errorf("too many positional arguments")
	}
	root := "."
	if len(positionals) == 1 {
		root = positionals[0]
	}
	return root, nil
}

// blastRadiusDiffError wraps a git-diff failure so the caller can surface the
// actionable "valid branch/ref" hint for a bad --ref.
type blastRadiusDiffError struct {
	ref string
	err error
}

func (e *blastRadiusDiffError) Error() string { return e.err.Error() }

func (e *blastRadiusDiffError) Unwrap() error { return e.err }

func defaultBlastRadiusLimits() blastRadiusLimits {
	return blastRadiusLimits{
		MaxTotalChars:         envInt("CODEMAP_BLAST_MAX_TOTAL_CHARS", 24000),
		MaxChangedFiles:       envInt("CODEMAP_BLAST_MAX_CHANGED_FILES", 20),
		MaxAffected:           envInt("CODEMAP_BLAST_MAX_AFFECTED", 12),
		MaxContext:            envInt("CODEMAP_BLAST_MAX_CONTEXT", 8),
		MaxSnippets:           envInt("CODEMAP_BLAST_MAX_SNIPPETS", 8),
		MaxSnippetsPerChanged: envInt("CODEMAP_BLAST_MAX_SNIPPETS_PER_CHANGED", 2),
		SnippetRadius:         envInt("CODEMAP_BLAST_SNIPPET_RADIUS", 2),
		MaxSnippetChars:       envInt("CODEMAP_BLAST_MAX_SNIPPET_CHARS", 700),
		MaxDiffChars:          envInt("CODEMAP_BLAST_MAX_DIFF_CHARS", 8000),
		MaxDepsChars:          envInt("CODEMAP_BLAST_MAX_DEPS_CHARS", 5000),
		MaxImportersChars:     envInt("CODEMAP_BLAST_MAX_IMPORTERS_CHARS", 6000),
		MaxImporterFiles:      envInt("CODEMAP_BLAST_MAX_IMPORTER_FILES", 8),
		MaxImportersPerFile:   envInt("CODEMAP_BLAST_MAX_IMPORTERS_PER_FILE", 12),
	}
}

func envInt(key string, fallback int) int {
	raw := strings.TrimSpace(os.Getenv(key))
	if raw == "" {
		return fallback
	}
	value, err := strconv.Atoi(raw)
	if err != nil {
		return fallback
	}
	return value
}

func clampBlastRadiusLimits(limits blastRadiusLimits) blastRadiusLimits {
	if limits.MaxTotalChars < 0 {
		limits.MaxTotalChars = 0
	}
	if limits.MaxChangedFiles < 0 {
		limits.MaxChangedFiles = 0
	}
	if limits.MaxAffected < 0 {
		limits.MaxAffected = 0
	}
	if limits.MaxContext < 0 {
		limits.MaxContext = 0
	}
	if limits.MaxSnippets < 0 {
		limits.MaxSnippets = 0
	}
	if limits.MaxSnippetsPerChanged < 0 {
		limits.MaxSnippetsPerChanged = 0
	}
	if limits.SnippetRadius < 0 {
		limits.SnippetRadius = 0
	}
	if limits.MaxSnippetChars < 0 {
		limits.MaxSnippetChars = 0
	}
	if limits.MaxDiffChars < 0 {
		limits.MaxDiffChars = 0
	}
	if limits.MaxDepsChars < 0 {
		limits.MaxDepsChars = 0
	}
	if limits.MaxImportersChars < 0 {
		limits.MaxImportersChars = 0
	}
	if limits.MaxImporterFiles < 0 {
		limits.MaxImporterFiles = 0
	}
	if limits.MaxImportersPerFile < 0 {
		limits.MaxImportersPerFile = 0
	}
	return limits
}

func resolveBlastRadiusRoot(root string) (string, func(), error) {
	cleanup := func() {}
	_, localErr := os.Stat(root)
	if isGitHubURL(root) {
		if os.IsNotExist(localErr) {
			repoName := extractRepoName(root)
			tempDir, err := cloneRepo(root, repoName)
			if err != nil {
				return "", cleanup, err
			}
			cleanup = func() { _ = os.RemoveAll(tempDir) }
			root = tempDir
		} else if localErr != nil {
			return "", cleanup, localErr
		}
	}

	absRoot, err := filepath.Abs(root)
	if err != nil {
		return "", cleanup, err
	}
	return absRoot, cleanup, nil
}

func buildBlastRadiusBundle(absRoot, ref string, limits blastRadiusLimits) (blastRadiusBundle, error) {
	diffInfo, err := scanner.GitDiffInfo(context.Background(), absRoot, ref)
	if err != nil {
		return blastRadiusBundle{}, &blastRadiusDiffError{ref: ref, err: err}
	}

	cmd.EnsureProjectConfig(absRoot)
	cfg := config.Load(absRoot)
	filters := scanner.Filters{Only: cfg.Only, Exclude: cfg.Exclude, MaxFiles: cfg.MaxFiles}
	gitCache := scanner.NewGitIgnoreCache(absRoot)
	allFiles, err := scanner.ScanFiles(context.Background(), absRoot, gitCache, filters.Only, filters.Exclude)
	if err != nil {
		return blastRadiusBundle{}, err
	}
	changedFiles := scanner.FilterToChangedWithInfo(allFiles, diffInfo)
	// Rank by churn before any cap so the cut lands on the smallest edits.
	// Scan order was path order, which on a 52-file refactor dropped the
	// highest-churn file and the app entry point while keeping tiny files
	// that sorted earlier (#149). Path breaks ties so output stays stable.
	sort.SliceStable(changedFiles, func(i, j int) bool {
		ci, cj := changedFiles[i].Added+changedFiles[i].Removed, changedFiles[j].Added+changedFiles[j].Removed
		if ci != cj {
			return ci > cj
		}
		return changedFiles[i].Path < changedFiles[j].Path
	})
	diffTotal := len(changedFiles)

	changedSet := make(map[string]bool, diffTotal)
	for _, file := range changedFiles {
		changedSet[filepath.ToSlash(file.Path)] = true
	}

	// Single ast-grep scan shared by impact analysis, the deps project, and the
	// file graph below. Previously each of those triggered its own full-repo
	// ScanForDeps, tripling latency on large repositories.
	var scanOutcome scanner.ScanOutcome
	if diffTotal > 0 {
		scanOutcome, err = scanForDepsOutcomeWithHint(absRoot, filters)
		if err != nil {
			return blastRadiusBundle{}, err
		}
	}
	analyses := scanOutcome.Analyses

	diffProject := scanner.Project{
		Root:    absRoot,
		Mode:    "tree",
		Files:   changedFiles,
		DiffRef: ref,
		Impact:  scanner.AnalyzeImpactFromAnalyses(changedFiles, analyses),
		Depth:   cfg.Depth,
		Only:    cfg.Only,
		Exclude: cfg.Exclude,
	}
	diffCapped := capBlastRadiusProject(diffProject, limits.MaxChangedFiles)

	depsProject := scanner.DepsProject{
		Root:         absRoot,
		Mode:         "deps",
		Files:        nil,
		ExternalDeps: map[string][]string{},
		DiffRef:      ref,
	}
	depsCapped := depsProject
	depsTotal := 0
	var allReports []scanner.ImportersReport
	var shownReports []scanner.ImportersReport
	var jsonReports []blastRadiusImporters
	var rawImpacted []blastRadiusRelation
	var impacted []blastRadiusRelation
	var rawContext []blastRadiusRelation
	var ctxRelations []blastRadiusRelation
	var snippets []blastRadiusSnippet

	if diffTotal > 0 {
		depsProject.Files = scanner.FilterAnalysisToChanged(analyses, changedSet)
		depsProject.ExternalDeps, err = scanner.ReadExternalDeps(context.Background(), absRoot, 0)
		if err != nil {
			return blastRadiusBundle{}, err
		}
		depsTotal = len(depsProject.Files)

		fg, err := scanner.BuildFileGraphFromOutcome(context.Background(), absRoot, scanOutcome, filters)
		if err != nil {
			return blastRadiusBundle{}, err
		}

		// Carry scan provenance into the deps project so a fail-closed scan
		// never reads as an empty, complete dependency graph.
		depsProject.Coverage = fg.Coverage.Contract()
		// Show the same files the diff panel shows. A prefix of scan order was
		// a different subset from the churn-ranked diff, so the two panels
		// described different changes.
		depsCapped = capBlastRadiusDepsProject(filterDepsToFiles(depsProject, diffCapped.Files), limits.MaxChangedFiles)

		// Analyze the FULL changed set; capping only limits what is displayed,
		// it must not shrink blast-radius analysis or the summary stats.
		for _, file := range changedFiles {
			report, reportErr := buildImportersReportFromGraph(absRoot, file.Path, fg)
			if reportErr != nil {
				return blastRadiusBundle{}, reportErr
			}
			allReports = append(allReports, report)
		}
		shownReports = allReports
		if len(diffCapped.Files) < len(allReports) {
			shownReports = allReports[:len(diffCapped.Files)]
		}
		for _, report := range shownReports {
			jsonReports = append(jsonReports, capBlastRadiusImportersReport(report, limits.MaxImportersPerFile))
		}

		rawImpacted = collectBlastRadiusImpacted(allReports, changedSet)
		rawContext = collectBlastRadiusContext(allReports, changedSet)
		impacted = capBlastRadiusRelations(rawImpacted, limits.MaxAffected)
		ctxRelations = capBlastRadiusRelations(rawContext, limits.MaxContext)
		snippets = buildBlastRadiusSnippets(absRoot, changedFiles, depsProject.Files, impacted, ctxRelations, limits)
	}

	summary := buildBlastRadiusSummary(diffCapped.Files, diffTotal, impacted, rawImpacted, ctxRelations, rawContext, allReports)
	affectedModules := collectTopologyImpacts(absRoot, changedFiles)

	bundle := blastRadiusBundle{
		Root:    absRoot,
		Ref:     ref,
		Summary: summary,
		Diff: blastRadiusDiff{
			Root:              diffCapped.Root,
			Name:              diffCapped.Name,
			Mode:              diffCapped.Mode,
			Files:             diffCapped.Files,
			DiffRef:           diffCapped.DiffRef,
			Impact:            diffCapped.Impact,
			Depth:             diffCapped.Depth,
			Only:              diffCapped.Only,
			Exclude:           diffCapped.Exclude,
			ChangedFilesTotal: diffTotal,
			DiffTotals:        diffCapped.DiffTotals,
		},
		Deps: blastRadiusDeps{
			Root:              depsCapped.Root,
			Mode:              depsCapped.Mode,
			Files:             depsCapped.Files,
			ExternalDeps:      depsCapped.ExternalDeps,
			DiffRef:           depsCapped.DiffRef,
			ChangedFilesTotal: depsTotal,
			CoverageStatus:    string(depsCapped.Coverage.Status),
			CoverageNotes:     coverageNotesFromSources(depsCapped.Coverage.Sources),
		},
		Importers:                    jsonReports,
		Limits:                       limits,
		ImpactedOutsideDiff:          impacted,
		DependencyContextOutsideDiff: ctxRelations,
		AffectedModules:              affectedModules,
		Snippets:                     snippets,
	}
	bundle.Rendered = buildBlastRadiusRendered(diffCapped, depsCapped, shownReports, diffTotal, limits)
	return bundle, nil
}

func capBlastRadiusProject(project scanner.Project, max int) scanner.Project {
	if max >= len(project.Files) {
		return project
	}
	// Keep the whole diff's counts so the rendered header states the total,
	// not the subset it happens to show.
	totals := &scanner.DiffTotals{Files: len(project.Files)}
	for _, f := range project.Files {
		totals.Added += f.Added
		totals.Removed += f.Removed
	}
	project.DiffTotals = totals
	project.Files = append([]scanner.FileInfo(nil), project.Files[:max]...)
	// Impact is an independent, usage-sorted list keyed by basename; filter it to
	// the files actually shown rather than slicing it by the changed-file cap,
	// which would drop or mis-attribute the diff impact footer.
	project.Impact = filterImpactToShownFiles(project.Impact, project.Files)
	return project
}

// filterImpactToShownFiles keeps only impact entries whose basename matches a
// shown changed file (or its directory, for package-style imports).
func filterImpactToShownFiles(impact []scanner.ImpactInfo, files []scanner.FileInfo) []scanner.ImpactInfo {
	if len(impact) == 0 {
		return impact
	}
	allowed := make(map[string]bool, len(files)*2)
	for _, f := range files {
		allowed[filepath.Base(f.Path)] = true
		dir := filepath.Dir(f.Path)
		if dir != "." && dir != "" {
			allowed[filepath.Base(dir)] = true
		}
	}
	var filtered []scanner.ImpactInfo
	for _, imp := range impact {
		if allowed[imp.File] {
			filtered = append(filtered, imp)
		}
	}
	return filtered
}

// filterDepsToFiles keeps the analyses for exactly the given changed files,
// in that order, so the deps panel covers the files the diff panel shows.
func filterDepsToFiles(project scanner.DepsProject, files []scanner.FileInfo) scanner.DepsProject {
	byPath := make(map[string]scanner.FileAnalysis, len(project.Files))
	for _, a := range project.Files {
		byPath[filepath.ToSlash(a.Path)] = a
	}
	kept := make([]scanner.FileAnalysis, 0, len(files))
	for _, f := range files {
		if a, ok := byPath[filepath.ToSlash(f.Path)]; ok {
			kept = append(kept, a)
		}
	}
	project.Files = kept
	return project
}

func capBlastRadiusDepsProject(project scanner.DepsProject, max int) scanner.DepsProject {
	if max >= len(project.Files) {
		return project
	}
	project.Files = append([]scanner.FileAnalysis(nil), project.Files[:max]...)
	return project
}

// coverageNotesFromSources flattens source-level detail into coverage notes,
// mirroring how the graph records blind-spot details for importers.
func coverageNotesFromSources(sources []analysis.Source) []string {
	var notes []string
	for _, source := range sources {
		if source.Detail != "" {
			notes = append(notes, source.Detail)
		}
	}
	return notes
}

func capBlastRadiusImportersReport(report scanner.ImportersReport, max int) blastRadiusImporters {
	cappedImporters := capStringSlice(report.Importers, max)
	cappedImports := capStringSlice(report.Imports, max)
	cappedHubImports := capStringSlice(report.HubImports, max)
	return blastRadiusImporters{
		Root:            report.Root,
		Mode:            report.Mode,
		File:            report.File,
		Importers:       cappedImporters,
		Imports:         cappedImports,
		HubImports:      cappedHubImports,
		ImporterCount:   report.ImporterCount,
		IsHub:           report.IsHub,
		ImportersTotal:  len(report.Importers),
		ImportsTotal:    len(report.Imports),
		HubImportsTotal: len(report.HubImports),
		CoverageStatus:  report.CoverageStatus,
		CoverageNotes:   append([]string(nil), report.CoverageNotes...),
	}
}

func capBlastRadiusRelations(relations []blastRadiusRelation, max int) []blastRadiusRelation {
	if max >= len(relations) {
		return append([]blastRadiusRelation(nil), relations...)
	}
	return append([]blastRadiusRelation(nil), relations[:max]...)
}

func capStringSlice(items []string, max int) []string {
	if max >= len(items) {
		return append([]string(nil), items...)
	}
	return append([]string(nil), items[:max]...)
}

func collectBlastRadiusImpacted(reports []scanner.ImportersReport, changedSet map[string]bool) []blastRadiusRelation {
	var impacted []blastRadiusRelation
	seen := make(map[string]bool)
	for _, report := range reports {
		for _, importer := range report.Importers {
			importer = filepath.ToSlash(importer)
			if changedSet[importer] {
				continue
			}
			key := importer + "|" + report.File
			if seen[key] {
				continue
			}
			seen[key] = true
			impacted = append(impacted, blastRadiusRelation{
				Path:             importer,
				Via:              report.File,
				Relation:         "imports_changed_file",
				ViaIsHub:         report.IsHub,
				ViaImporterCount: report.ImporterCount,
			})
		}
	}

	sort.Slice(impacted, func(i, j int) bool {
		if impacted[i].ViaImporterCount != impacted[j].ViaImporterCount {
			return impacted[i].ViaImporterCount > impacted[j].ViaImporterCount
		}
		if impacted[i].Path != impacted[j].Path {
			return impacted[i].Path < impacted[j].Path
		}
		return impacted[i].Via < impacted[j].Via
	})
	return impacted
}

func collectBlastRadiusContext(reports []scanner.ImportersReport, changedSet map[string]bool) []blastRadiusRelation {
	var context []blastRadiusRelation
	seen := make(map[string]bool)
	for _, report := range reports {
		hubImports := make(map[string]bool, len(report.HubImports))
		for _, hub := range report.HubImports {
			hubImports[filepath.ToSlash(hub)] = true
		}
		for _, imp := range report.Imports {
			imp = filepath.ToSlash(imp)
			if changedSet[imp] {
				continue
			}
			key := imp + "|" + report.File
			if seen[key] {
				continue
			}
			seen[key] = true
			relation := "internal_dependency"
			if hubImports[imp] {
				relation = "shared_hub_dependency"
			}
			context = append(context, blastRadiusRelation{
				Path:     imp,
				Via:      report.File,
				Relation: relation,
				IsHub:    hubImports[imp],
			})
		}
	}

	sort.Slice(context, func(i, j int) bool {
		leftOrder := 1
		rightOrder := 1
		if context[i].Relation == "shared_hub_dependency" {
			leftOrder = 0
		}
		if context[j].Relation == "shared_hub_dependency" {
			rightOrder = 0
		}
		if leftOrder != rightOrder {
			return leftOrder < rightOrder
		}
		if context[i].Path != context[j].Path {
			return context[i].Path < context[j].Path
		}
		return context[i].Via < context[j].Via
	})
	return context
}

func buildBlastRadiusSummary(diffFiles []scanner.FileInfo, diffTotal int, impacted []blastRadiusRelation, rawImpacted []blastRadiusRelation, context []blastRadiusRelation, rawContext []blastRadiusRelation, reports []scanner.ImportersReport) blastRadiusSummary {
	summary := blastRadiusSummary{
		ChangedFiles:                      len(diffFiles),
		ChangedFilesTotal:                 diffTotal,
		FilesWithDependents:               countReportsWithDependents(reports),
		ImpactedOutsideDiffTotal:          uniqueRelationPaths(rawImpacted),
		ImpactedOutsideDiffShown:          uniqueRelationPaths(impacted),
		DependencyContextOutsideDiffTotal: uniqueRelationPaths(rawContext),
		DependencyContextOutsideDiffShown: uniqueRelationPaths(context),
		MaxDirectDependents:               maxDirectDependents(reports),
	}

	for _, report := range reports {
		if report.ImporterCount == 0 {
			continue
		}
		if summary.HighestBlastRadius == nil || report.ImporterCount > summary.HighestBlastRadius.ImporterCount || (report.ImporterCount == summary.HighestBlastRadius.ImporterCount && report.File < summary.HighestBlastRadius.File) {
			summary.HighestBlastRadius = &blastRadiusHighest{
				File:          report.File,
				ImporterCount: report.ImporterCount,
			}
		}
	}
	return summary
}

func countReportsWithDependents(reports []scanner.ImportersReport) int {
	count := 0
	for _, report := range reports {
		if report.ImporterCount > 0 {
			count++
		}
	}
	return count
}

func uniqueRelationPaths(items []blastRadiusRelation) int {
	seen := make(map[string]bool, len(items))
	for _, item := range items {
		seen[item.Path] = true
	}
	return len(seen)
}

func maxDirectDependents(reports []scanner.ImportersReport) int {
	max := 0
	for _, report := range reports {
		if report.ImporterCount > max {
			max = report.ImporterCount
		}
	}
	return max
}

func buildBlastRadiusSnippets(root string, diffFiles []scanner.FileInfo, depsFiles []scanner.FileAnalysis, impacted []blastRadiusRelation, context []blastRadiusRelation, limits blastRadiusLimits) []blastRadiusSnippet {
	if limits.MaxSnippets == 0 || limits.MaxSnippetsPerChanged == 0 {
		return nil
	}

	changedMeta := make(map[string]blastChangedMeta, len(diffFiles))
	for _, file := range diffFiles {
		meta := newBlastChangedMeta(file.Path)
		changedMeta[filepath.ToSlash(file.Path)] = meta
	}
	for _, file := range depsFiles {
		meta := newBlastChangedMeta(file.Path)
		meta.Functions = append([]string(nil), file.Functions...)
		changedMeta[filepath.ToSlash(file.Path)] = meta
	}

	var snippets []blastRadiusSnippet
	perChanged := make(map[string]int)

	for _, item := range impacted {
		if len(snippets) >= limits.MaxSnippets {
			break
		}
		if perChanged[item.Via] >= limits.MaxSnippetsPerChanged {
			continue
		}
		snippet := findBlastRadiusSnippet(root, item.Path, item.Via, "impacted_outside_diff", fmt.Sprintf("depends on changed file %s", item.Via), changedMeta, limits)
		if snippet == nil {
			continue
		}
		snippets = append(snippets, *snippet)
		perChanged[item.Via]++
	}

	for _, item := range context {
		if len(snippets) >= limits.MaxSnippets {
			break
		}
		if perChanged[item.Via] >= limits.MaxSnippetsPerChanged {
			continue
		}
		snippet := findBlastRadiusSnippet(root, item.Path, item.Via, "dependency_context_outside_diff", fmt.Sprintf("reachable from changed file %s", item.Via), changedMeta, limits)
		if snippet == nil {
			continue
		}
		snippets = append(snippets, *snippet)
		perChanged[item.Via]++
	}

	return snippets
}

func newBlastChangedMeta(file string) blastChangedMeta {
	file = filepath.ToSlash(file)
	stem := strings.TrimSuffix(path.Base(file), path.Ext(file))
	dir := path.Dir(file)
	if dir == "." {
		dir = ""
	}
	dirBase := ""
	if dir != "" {
		dirBase = path.Base(dir)
	}
	return blastChangedMeta{
		Stem:      stem,
		Dir:       dir,
		DirBase:   dirBase,
		PathNoExt: strings.TrimSuffix(file, path.Ext(file)),
	}
}

func findBlastRadiusSnippet(root, targetPath, via, category, reason string, changedMeta map[string]blastChangedMeta, limits blastRadiusLimits) *blastRadiusSnippet {
	absPath := filepath.Join(root, filepath.FromSlash(targetPath))
	data, err := os.ReadFile(absPath)
	if err != nil {
		return nil
	}
	content := string(data)
	if !utf8.ValidString(content) {
		content = strings.ToValidUTF8(content, "\uFFFD")
	}
	lines := strings.Split(strings.ReplaceAll(content, "\r\n", "\n"), "\n")
	if len(lines) == 0 {
		return nil
	}

	for _, term := range blastSnippetTerms(changedMeta[via]) {
		for idx, line := range lines {
			if !blastLineMatchesTerm(line, term) {
				continue
			}
			language := scanner.DetectLanguage(targetPath)
			if language == "" {
				language = "text"
			}
			return &blastRadiusSnippet{
				Category:    category,
				Path:        targetPath,
				Via:         via,
				Reason:      reason,
				MatchedTerm: term.Value,
				MatchKind:   term.Kind,
				Language:    language,
				Excerpt:     buildBlastSnippetExcerpt(lines, idx, limits.SnippetRadius, limits.MaxSnippetChars),
			}
		}
	}

	return nil
}

type blastSnippetTerm struct {
	Value string
	Kind  string
	Regex *regexp.Regexp
}

func blastSnippetTerms(meta blastChangedMeta) []blastSnippetTerm {
	var functions []string
	functions = append(functions, meta.Functions...)
	sort.Slice(functions, func(i, j int) bool {
		if utf8.RuneCountInString(functions[i]) != utf8.RuneCountInString(functions[j]) {
			return utf8.RuneCountInString(functions[i]) > utf8.RuneCountInString(functions[j])
		}
		return functions[i] < functions[j]
	})

	var terms []blastSnippetTerm
	seen := make(map[string]bool)
	for _, fn := range functions {
		fn = strings.TrimSpace(fn)
		if fn == "" || seen[fn] {
			continue
		}
		seen[fn] = true
		terms = append(terms, blastSnippetTerm{
			Value: fn,
			Kind:  "symbol",
			Regex: regexp.MustCompile(`\b` + regexp.QuoteMeta(fn) + `\b`),
		})
	}

	for _, candidate := range []blastSnippetTerm{
		{Value: meta.PathNoExt, Kind: "path"},
		{Value: meta.Dir, Kind: "path"},
		{Value: meta.DirBase, Kind: "identifier"},
		{Value: meta.Stem, Kind: "identifier"},
	} {
		value := strings.TrimSpace(candidate.Value)
		if value == "" || seen[value] {
			continue
		}
		seen[value] = true
		terms = append(terms, blastSnippetTerm{Value: value, Kind: candidate.Kind})
	}

	return terms
}

func blastLineMatchesTerm(line string, term blastSnippetTerm) bool {
	switch term.Kind {
	case "symbol":
		return term.Regex != nil && term.Regex.MatchString(line)
	default:
		return strings.Contains(line, term.Value)
	}
}

func buildBlastSnippetExcerpt(lines []string, index, radius, maxChars int) string {
	start := index - radius
	if start < 0 {
		start = 0
	}
	end := index + radius + 1
	if end > len(lines) {
		end = len(lines)
	}

	var excerpt []string
	for i := start; i < end; i++ {
		excerpt = append(excerpt, fmt.Sprintf("%4d | %s", i+1, lines[i]))
	}
	text := strings.Join(excerpt, "\n")
	if runeLen(text) <= maxChars {
		return text
	}
	return truncateRunes(text, maxChars, "\n... [truncated]")
}

func buildBlastRadiusRendered(diffProject scanner.Project, depsProject scanner.DepsProject, reports []scanner.ImportersReport, diffTotal int, limits blastRadiusLimits) blastRadiusRendered {
	if len(diffProject.Files) == 0 {
		ref := diffProject.DiffRef
		if ref == "" {
			ref = "main"
		}
		// Distinguish "nothing changed" from "files changed but the display cap
		// hid all of them" so the rendered output never contradicts the summary.
		if diffTotal > 0 {
			return blastRadiusRendered{
				Diff: fmt.Sprintf("%d file(s) changed vs %s; none shown (raise --max-changed-files).\n", diffTotal, ref),
				Deps: "Changed files omitted by --max-changed-files.\n",
			}
		}
		return blastRadiusRendered{
			Diff: fmt.Sprintf("No files changed vs %s\n", ref),
			Deps: "No changed source files to analyze.\n",
		}
	}

	rendered := blastRadiusRendered{
		Diff: truncateBlastRadiusText(renderDiffProject(diffProject), limits.MaxDiffChars, "diff"),
		Deps: truncateBlastRadiusText(renderDepsProject(depsProject), limits.MaxDepsChars, "deps"),
	}

	// Only render importer sections that actually have content; a changed file
	// with no importers and no hub imports would otherwise emit an empty block.
	type renderableImporter struct {
		file string
		text string
	}
	var renderable []renderableImporter
	for _, report := range reports {
		// Decide on the data, not on the rendered text: every report now
		// carries a coverage line, so rendering first would make a file with
		// no importers look like it had content.
		if len(report.Importers) == 0 && len(report.HubImports) == 0 {
			continue
		}
		text := renderImportersReportString(report)
		if strings.TrimSpace(text) == "" {
			continue
		}
		renderable = append(renderable, renderableImporter{file: report.File, text: text})
	}

	importerBudget := limits.MaxImportersChars
	for _, item := range renderable {
		if len(rendered.Importers) >= limits.MaxImporterFiles || importerBudget <= 0 {
			break
		}
		perFileBudget := minInt(importerBudget, 1200)
		text := truncateBlastRadiusText(item.text, perFileBudget, "importers:"+item.file)
		rendered.Importers = append(rendered.Importers, blastRadiusRenderedImporter{
			File: item.file,
			Text: text,
		})
		importerBudget -= runeLen(text)
	}
	rendered.ImportersTruncated = len(rendered.Importers) < len(renderable)

	return rendered
}

func renderBlastRadiusMarkdown(bundle blastRadiusBundle) string {
	builder := newBlastOutputBuilder(bundle.Limits.MaxTotalChars)

	var summary strings.Builder
	summary.WriteString("# Codemap Blast Radius\n\n")
	_, _ = fmt.Fprintf(&summary, "- Root: `%s`\n", bundle.Root)
	_, _ = fmt.Fprintf(&summary, "- Base ref: `%s`\n\n", bundle.Ref)
	summary.WriteString("## Summary\n\n")
	if bundle.Summary.ChangedFiles < bundle.Summary.ChangedFilesTotal {
		_, _ = fmt.Fprintf(&summary, "- Changed files: %d shown of %d (ranked by churn; raise --max-changed-files)\n", bundle.Summary.ChangedFiles, bundle.Summary.ChangedFilesTotal)
	} else {
		_, _ = fmt.Fprintf(&summary, "- Changed files: %d shown of %d\n", bundle.Summary.ChangedFiles, bundle.Summary.ChangedFilesTotal)
	}
	_, _ = fmt.Fprintf(&summary, "- Changed files with direct dependents: %d\n", bundle.Summary.FilesWithDependents)
	_, _ = fmt.Fprintf(&summary, "- Affected files outside diff: %d shown of %d\n", bundle.Summary.ImpactedOutsideDiffShown, bundle.Summary.ImpactedOutsideDiffTotal)
	_, _ = fmt.Fprintf(&summary, "- Dependency context outside diff: %d shown of %d\n", bundle.Summary.DependencyContextOutsideDiffShown, bundle.Summary.DependencyContextOutsideDiffTotal)
	if bundle.Summary.HighestBlastRadius != nil {
		_, _ = fmt.Fprintf(&summary, "- Highest blast radius: `%s` (%d direct dependents)\n", bundle.Summary.HighestBlastRadius.File, bundle.Summary.HighestBlastRadius.ImporterCount)
	}
	_, _ = fmt.Fprintf(&summary, "- Output budgets: total %d chars, diff %d, deps %d, importers %d\n", bundle.Limits.MaxTotalChars, bundle.Limits.MaxDiffChars, bundle.Limits.MaxDepsChars, bundle.Limits.MaxImportersChars)
	_, _ = fmt.Fprintf(&summary, "- Snippet limits: %d total, %d per changed file, %d chars max\n\n", bundle.Limits.MaxSnippets, bundle.Limits.MaxSnippetsPerChanged, bundle.Limits.MaxSnippetChars)
	if !builder.Append(summary.String(), "summary") {
		return builder.String()
	}

	if bundle.Summary.ChangedFilesTotal == 0 {
		empty := fmt.Sprintf("## No Changes\n\n- No files changed vs `%s`.\n- Dependency, snippet, and importer sections are omitted.\n", bundle.Ref)
		builder.Append(empty, "no changes")
		return builder.String()
	}

	if len(bundle.ImpactedOutsideDiff) > 0 {
		var section strings.Builder
		section.WriteString("## Affected Outside Diff\n\n")
		for _, item := range bundle.ImpactedOutsideDiff {
			section.WriteString(fmt.Sprintf("- `%s` depends on changed file `%s`", item.Path, item.Via))
			if item.ViaIsHub {
				section.WriteString(fmt.Sprintf(" [hub, %d dependents]", item.ViaImporterCount))
			}
			section.WriteString("\n")
		}
		section.WriteString("\n")
		if !builder.Append(section.String(), "affected outside diff") {
			return builder.String()
		}
	}

	if len(bundle.AffectedModules) > 0 {
		var section strings.Builder
		section.WriteString("## Affected Modules\n\n")
		for _, item := range bundle.AffectedModules {
			_, _ = fmt.Fprintf(&section, "- `%s` (`%s`): %s", item.Name, item.ID, item.Relation)
			if item.Via != "" {
				_, _ = fmt.Fprintf(&section, " via `%s`", item.Via)
			}
			if item.Dependents > 0 {
				_, _ = fmt.Fprintf(&section, " [%d dependent modules]", item.Dependents)
			}
			section.WriteString("\n")
		}
		section.WriteString("\n")
		if !builder.Append(section.String(), "affected modules") {
			return builder.String()
		}
	}

	if len(bundle.DependencyContextOutsideDiff) > 0 {
		var section strings.Builder
		section.WriteString("## Dependency Context Outside Diff\n\n")
		for _, item := range bundle.DependencyContextOutsideDiff {
			section.WriteString(fmt.Sprintf("- changed file `%s` reaches `%s`", item.Via, item.Path))
			if item.Relation == "shared_hub_dependency" {
				section.WriteString(" [shared hub]")
			}
			section.WriteString("\n")
		}
		section.WriteString("\n")
		if !builder.Append(section.String(), "dependency context") {
			return builder.String()
		}
	}

	if len(bundle.Snippets) > 0 {
		var section strings.Builder
		section.WriteString("## Impact Snippets\n")
		for _, snippet := range bundle.Snippets {
			section.WriteString("\n")
			section.WriteString(fmt.Sprintf("### `%s` via `%s`\n\n", snippet.Path, snippet.Via))
			section.WriteString(fmt.Sprintf("- Reason: %s\n", snippet.Reason))
			section.WriteString(fmt.Sprintf("- Match: `%s` (%s)\n\n", snippet.MatchedTerm, snippet.MatchKind))
			section.WriteString("```" + snippet.Language + "\n")
			section.WriteString(snippet.Excerpt)
			section.WriteString("\n```\n")
		}
		section.WriteString("\n")
		if !builder.Append(section.String(), "impact snippets") {
			return builder.String()
		}
	}

	diffSection := "## Diff\n\n```text\n" + bundle.Rendered.Diff + "\n```\n\n"
	if !builder.Append(diffSection, "diff section") {
		return builder.String()
	}

	depsSection := "## Dependency Flow (Changed Files)\n\n```text\n" + bundle.Rendered.Deps + "\n```\n"
	if !builder.Append(depsSection, "deps section") {
		return builder.String()
	}

	if len(bundle.Rendered.Importers) > 0 {
		var section strings.Builder
		section.WriteString("\n## Importers\n")
		for _, importer := range bundle.Rendered.Importers {
			section.WriteString(fmt.Sprintf("\n### `%s`\n\n```text\n%s\n```\n", importer.File, importer.Text))
		}
		if bundle.Rendered.ImportersTruncated {
			section.WriteString("\n... [additional importer sections omitted]\n")
		}
		builder.Append(section.String(), "importers section")
	}

	return builder.String()
}

func renderBlastRadiusText(bundle blastRadiusBundle) string {
	builder := newBlastOutputBuilder(bundle.Limits.MaxTotalChars)

	var summary strings.Builder
	summary.WriteString("CODEMAP BLAST RADIUS\n")
	summary.WriteString(fmt.Sprintf("root=%s\n", bundle.Root))
	summary.WriteString(fmt.Sprintf("ref=%s\n\n", bundle.Ref))
	summary.WriteString("[summary]\n")
	summary.WriteString(fmt.Sprintf("changed_files=%d/%d\n", bundle.Summary.ChangedFiles, bundle.Summary.ChangedFilesTotal))
	summary.WriteString(fmt.Sprintf("files_with_dependents=%d\n", bundle.Summary.FilesWithDependents))
	summary.WriteString(fmt.Sprintf("impacted_outside_diff=%d/%d\n", bundle.Summary.ImpactedOutsideDiffShown, bundle.Summary.ImpactedOutsideDiffTotal))
	summary.WriteString(fmt.Sprintf("dependency_context_outside_diff=%d/%d\n", bundle.Summary.DependencyContextOutsideDiffShown, bundle.Summary.DependencyContextOutsideDiffTotal))
	summary.WriteString(fmt.Sprintf("output_budgets=%d_total,%d_diff,%d_deps,%d_importers\n", bundle.Limits.MaxTotalChars, bundle.Limits.MaxDiffChars, bundle.Limits.MaxDepsChars, bundle.Limits.MaxImportersChars))
	summary.WriteString(fmt.Sprintf("snippet_limits=%d_total,%d_per_changed,%d_chars\n\n", bundle.Limits.MaxSnippets, bundle.Limits.MaxSnippetsPerChanged, bundle.Limits.MaxSnippetChars))
	if !builder.Append(summary.String(), "summary") {
		return builder.String()
	}

	if bundle.Summary.ChangedFilesTotal == 0 {
		empty := fmt.Sprintf("[no_changes]\nNo files changed vs %s.\nDependency, snippet, and importer sections are omitted.\n", bundle.Ref)
		builder.Append(empty, "no changes")
		return builder.String()
	}

	if len(bundle.ImpactedOutsideDiff) > 0 {
		var section strings.Builder
		section.WriteString("[affected_outside_diff]\n")
		for _, item := range bundle.ImpactedOutsideDiff {
			section.WriteString(fmt.Sprintf("%s <= %s\n", item.Path, item.Via))
		}
		section.WriteString("\n")
		if !builder.Append(section.String(), "affected outside diff") {
			return builder.String()
		}
	}

	if len(bundle.AffectedModules) > 0 {
		var section strings.Builder
		section.WriteString("[affected_modules]\n")
		for _, item := range bundle.AffectedModules {
			_, _ = fmt.Fprintf(&section, "%s (%s): %s", item.Name, item.ID, item.Relation)
			if item.Via != "" {
				_, _ = fmt.Fprintf(&section, " <= %s", item.Via)
			}
			section.WriteString("\n")
		}
		section.WriteString("\n")
		if !builder.Append(section.String(), "affected modules") {
			return builder.String()
		}
	}

	if len(bundle.DependencyContextOutsideDiff) > 0 {
		var section strings.Builder
		section.WriteString("[dependency_context_outside_diff]\n")
		for _, item := range bundle.DependencyContextOutsideDiff {
			section.WriteString(fmt.Sprintf("%s => %s", item.Via, item.Path))
			if item.Relation == "shared_hub_dependency" {
				section.WriteString(" [shared hub]")
			}
			section.WriteString("\n")
		}
		section.WriteString("\n")
		if !builder.Append(section.String(), "dependency context") {
			return builder.String()
		}
	}

	if len(bundle.Snippets) > 0 {
		var section strings.Builder
		section.WriteString("[impact_snippets]\n")
		for _, snippet := range bundle.Snippets {
			section.WriteString(fmt.Sprintf("\n%s <= %s [%s]\n", snippet.Path, snippet.Via, snippet.MatchedTerm))
			section.WriteString(snippet.Excerpt)
			section.WriteString("\n")
		}
		section.WriteString("\n")
		if !builder.Append(section.String(), "impact snippets") {
			return builder.String()
		}
	}

	if !builder.Append("[diff]\n"+bundle.Rendered.Diff+"\n", "diff section") {
		return builder.String()
	}
	if !builder.Append("[deps]\n"+bundle.Rendered.Deps+"\n", "deps section") {
		return builder.String()
	}

	if len(bundle.Rendered.Importers) > 0 {
		var section strings.Builder
		for _, importer := range bundle.Rendered.Importers {
			section.WriteString(fmt.Sprintf("\n[importers] %s\n%s\n", importer.File, importer.Text))
		}
		if bundle.Rendered.ImportersTruncated {
			section.WriteString("\n... [additional importer sections omitted]\n")
		}
		builder.Append(section.String(), "importers section")
	}

	return builder.String()
}

func newBlastOutputBuilder(total int) *blastOutputBuilder {
	return &blastOutputBuilder{total: total, remaining: total}
}

func (b *blastOutputBuilder) Append(text, label string) bool {
	if b.remaining <= 0 {
		return false
	}
	if runeLen(text) <= b.remaining {
		b.builder.WriteString(text)
		b.remaining -= runeLen(text)
		return true
	}
	marker := fmt.Sprintf("\n... [%s omitted after total budget %d chars]\n", label, b.total)
	// Reserve room to close a code fence if truncation lands mid-block, so the
	// emitted markdown never has a dangling ``` opener.
	fenceClose := "\n```\n"
	fenceReserve := 0
	if strings.Contains(text, "```") {
		fenceReserve = runeLen(fenceClose)
	}
	keep := b.remaining - runeLen(marker) - fenceReserve
	if keep < 0 {
		keep = 0
	}
	kept := firstRunes(text, keep)
	b.builder.WriteString(kept)
	if strings.Count(kept, "```")%2 == 1 {
		b.builder.WriteString(fenceClose)
	}
	b.builder.WriteString(marker)
	b.remaining = 0
	return false
}

func (b *blastOutputBuilder) String() string {
	return b.builder.String()
}

func truncateBlastRadiusText(text string, maxChars int, label string) string {
	if maxChars <= 0 {
		return fmt.Sprintf("... [%s omitted]\n", label)
	}
	if runeLen(text) <= maxChars {
		return text
	}
	marker := fmt.Sprintf("\n... [%s truncated to %d chars]\n", label, maxChars)
	keep := maxChars - runeLen(marker)
	if keep < 0 {
		keep = 0
	}
	return firstRunes(text, keep) + marker
}

func renderDiffProject(project scanner.Project) string {
	var buf bytes.Buffer
	render.Tree(&buf, project)
	return stripANSI(buf.String())
}

func renderDepsProject(project scanner.DepsProject) string {
	var buf bytes.Buffer
	render.Depgraph(context.Background(), &buf, project)
	return stripANSI(buf.String())
}

func renderImportersReportString(report scanner.ImportersReport) string {
	var buf bytes.Buffer
	renderImportersReport(&buf, report)
	return buf.String()
}

// renderImportersReportCLI is the interactive `--importers` output: unlike the
// token-budgeted blast-radius bundle (which omits empty sections), a human ran
// this command and deserves an explanation when the answer is "none".
func renderImportersReportCLI(w io.Writer, report scanner.ImportersReport) {
	if len(report.Importers) == 0 && len(report.HubImports) == 0 {
		if report.NotIndexed {
			// Distinct from "scanned and found zero importers": codemap never
			// looked at this file, so a bare "No files import X" here would be
			// indistinguishable from a genuine negative and read as a
			// confident answer instead of a blind spot.
			fmt.Fprintf(w, "%s: not indexed (under a hidden or excluded folder, or the path doesn't exist).\n", report.File)
			fmt.Fprintln(w, "   codemap never scanned this file, so this is not a confirmed zero-importers result.")
			renderCoverage(w, report.CoverageStatus, report.CoverageNotes)
			return
		}
		if report.CoverageStatus == string(analysis.CoverageUnavailable) {
			// No dependency scan ran (above the file bound, ast-grep missing),
			// so there is no answer, and "No files import" would be a
			// confident zero with nothing behind it (#186, #138).
			fmt.Fprintf(w, "Importers of %s: unknown, no dependency scan ran.\n", report.File)
			renderCoverage(w, report.CoverageStatus, report.CoverageNotes)
			return
		}
		if report.Package != "" && report.PackageSiblings > 0 {
			// A Go file's importers are the files that import its package, so
			// a zero here says nothing about the package's own files: those
			// references are not edges in this graph, and the reader has to
			// check them by hand. Say so, with the count, instead of printing
			// a bare zero that reads as "nothing depends on this".
			fmt.Fprintf(w, "No cross-package importers of %s. Same-package references are not modeled (%s in package %s).\n",
				report.File, pluralFiles(report.PackageSiblings, "other file"), report.Package)
		} else {
			fmt.Fprintf(w, "No files import %s.\n", report.File)
		}
		// Show scan provenance even for an empty answer, so a partial scan
		// isn't read as a confident negative.
		renderCoverage(w, report.CoverageStatus, report.CoverageNotes)
		return
	}
	renderImportersReport(w, report)
}

// importersGranularity names the unit an importer count was measured at when
// it is not the file: Go imports name packages, so "21 files import
// watch/events.go" means 21 files import package watch, and a reader must not
// take the number as evidence that any of them references events.go itself.
func importersGranularity(report scanner.ImportersReport) string {
	if report.Package == "" {
		return ""
	}
	return fmt.Sprintf(" (package %s: Go imports name packages, not files)", report.Package)
}

func pluralFiles(n int, noun string) string {
	if n == 1 {
		return fmt.Sprintf("%d %s", n, noun)
	}
	return fmt.Sprintf("%d %ss", n, noun)
}

func renderImportersReport(w io.Writer, report scanner.ImportersReport) {
	if scanner.CountHubImporters(report.Importers) >= scanner.HubThreshold {
		fmt.Fprintf(w, "⚠️  HUB FILE: %s\n", report.File)
		fmt.Fprintf(w, "   Imported by %d files%s - changes have wide impact!\n", len(report.Importers), importersGranularity(report))
		fmt.Fprintln(w)
		fmt.Fprintln(w, "   Dependents:")
		for i, imp := range report.Importers {
			if i >= 5 {
				fmt.Fprintf(w, "   ... and %d more\n", len(report.Importers)-5)
				break
			}
			fmt.Fprintf(w, "   • %s\n", imp)
		}
	} else if len(report.Importers) > 0 {
		fmt.Fprintf(w, "📍 File: %s\n", report.File)
		fmt.Fprintf(w, "   Imported by %d file(s)%s\n", len(report.Importers), importersGranularity(report))
		for _, imp := range report.Importers {
			fmt.Fprintf(w, "   • %s\n", imp)
		}
	}

	if len(report.HubImports) > 0 {
		if len(report.Importers) == 0 {
			fmt.Fprintf(w, "📍 File: %s\n", report.File)
		}
		// Every non-test file of a hub Go package is a hub, so list the
		// package once with its file count rather than each file.
		fmt.Fprintf(w, "   Imports %d hub(s): %s\n", len(report.HubImports), strings.Join(scanner.CollapseGoPackageFiles(report.HubImports), ", "))
	}

	renderCoverage(w, report.CoverageStatus, report.CoverageNotes)
}

func renderCoverage(w io.Writer, status string, notes []string) {
	if status == "" {
		return
	}
	if len(notes) == 0 {
		fmt.Fprintf(w, "Coverage: %s\n", status)
		return
	}
	fmt.Fprintf(w, "Coverage: %s — %s\n", status, strings.Join(notes, "; "))
}

func buildImportersReportFromGraph(root, file string, fg *scanner.FileGraph) (scanner.ImportersReport, error) {
	if canonical, err := filepath.EvalSymlinks(root); err == nil {
		root = canonical
	}
	filePath := file
	if !filepath.IsAbs(filePath) {
		filePath = filepath.Join(root, filepath.FromSlash(filePath))
	}
	if canonical, err := filepath.EvalSymlinks(filePath); err == nil {
		filePath = canonical
	}
	rel, err := filepath.Rel(root, filePath)
	if err != nil {
		return scanner.ImportersReport{}, fmt.Errorf("resolve file %q relative to project root %q: %w", file, root, err)
	}
	if rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) || filepath.IsAbs(rel) {
		return scanner.ImportersReport{}, fmt.Errorf("file %q is outside project root %q", file, root)
	}
	file = rel
	file = filepath.ToSlash(file)

	// Preserve scan order (do not sort): this helper also backs the pre-existing
	// `codemap --importers` command, whose output ordering callers depend on.
	importers := append([]string(nil), fg.Importers[file]...)
	imports := append([]string(nil), fg.Imports[file]...)

	// NotIndexed distinguishes "codemap scanned this file and it genuinely
	// has zero importers" from "codemap never looked at this file at all"
	// (e.g. it lives under a hidden or excluded directory, or the path
	// doesn't exist). CoverageStatus/CoverageNotes below still describe the
	// *scan as a whole* (complete/partial/unavailable) and are left as-is:
	// an authoritative, complete scan can still miss one particular file
	// simply because that file was outside its scanned set, which is
	// exactly the gap NotIndexed exists to surface without redefining what
	// "complete" means for the project overall.
	report := scanner.ImportersReport{
		Root:           root,
		Mode:           "importers",
		File:           file,
		Importers:      importers,
		Imports:        imports,
		ImporterCount:  len(importers),
		IsHub:          fg.IsHub(file),
		NotIndexed:     !fg.Indexed(file),
		CoverageStatus: string(fg.Coverage.EffectiveStatus()),
		CoverageNotes:  append([]string(nil), fg.Coverage.Notes...),
	}

	if pkg, pkgFiles, ok := fg.GoPackage(file); ok {
		report.Package = pkg
		report.PackageSiblings = len(pkgFiles)
		if !scanner.IsTestFile(file) {
			// pkgFiles holds this file too; a _test.go file is in the package
			// but never in the index, so every indexed file is a sibling of it.
			report.PackageSiblings--
		}
	}

	for _, imp := range imports {
		if fg.IsHub(imp) {
			report.HubImports = append(report.HubImports, imp)
		}
	}
	return report, nil
}

func printAstGrepInstallHint(w io.Writer, err error) {
	fmt.Fprintf(w, "Error: %v\n", err)
	fmt.Fprintln(w)
	fmt.Fprintln(w, "The --deps feature requires ast-grep. Install it with:")
	fmt.Fprintln(w, "  brew install ast-grep         # macOS/Linux (installs as 'sg')")
	fmt.Fprintln(w, "  cargo install ast-grep        # installs as 'ast-grep'")
	fmt.Fprintln(w, "  pipx install ast-grep         # installs as 'ast-grep'")
	fmt.Fprintln(w, "  python3 -m pip install ast-grep-cli")
	fmt.Fprintln(w)
	fmt.Fprintln(w, "Standard release tarballs ship codemap without the ast-grep binary.")
	fmt.Fprintln(w, "Use a codemap-full archive for self-contained CI installs, or install ast-grep separately.")
}

func stripANSI(text string) string {
	return ansiSequencePattern.ReplaceAllString(text, "")
}

func runeLen(text string) int {
	return utf8.RuneCountInString(text)
}

func firstRunes(text string, max int) string {
	if max <= 0 {
		return ""
	}
	if runeLen(text) <= max {
		return text
	}
	var builder strings.Builder
	count := 0
	for _, r := range text {
		if count >= max {
			break
		}
		builder.WriteRune(r)
		count++
	}
	return builder.String()
}

func truncateRunes(text string, max int, suffix string) string {
	if runeLen(text) <= max {
		return text
	}
	keep := max - runeLen(suffix)
	if keep < 0 {
		keep = 0
	}
	return firstRunes(text, keep) + suffix
}

func minInt(a, b int) int {
	if a < b {
		return a
	}
	return b
}