boyter
diff --git a/‎README.md‎
Lines changed: 57 additions & 3 deletions b/‎README.md‎
Lines changed: 57 additions & 3 deletions
diff --git a/‎config.go‎
Lines changed: 2 additions & 0 deletions b/‎config.go‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎mcp.go‎
Lines changed: 93 additions & 0 deletions b/‎mcp.go‎
Lines changed: 93 additions & 0 deletions
@@ -314,6 +314,8 @@ Flags:
       --count-as string                     count extension as language [e.g. jsp:htm,chead:"C Header" maps extension jsp to html and chead to C Header]
       --count-as-pattern stringArray        count files matching a path pattern as a new named category backed by a base language [repeatable; pattern is glob by default, prefix with re: for regex; e.g. *_spec.rb:"Ruby Spec":Ruby or re:\.test\.js$:"JavaScript Tests":JavaScript]
       --count-ignore                        set to allow .gitignore and .ignore files to be counted
+      --coupling                            render the change-coupling report (file pairs that change together over recent git history)
+      --coupling-for string                 blast-radius view: given a file path, show what tends to change with it over recent git history
       --currency-symbol string              set currency symbol (default "$")
       --debug                               enable debug output
       --depth int                           commit window size for git history reports; 0 means entire history (large repos may be slow) (default 1000)
@@ -835,7 +837,7 @@ LOCOMO is a rough estimator with known limitations:
 
 ### Git Insight Reports
 
-In addition to counting the working tree, `scc` can run four git-aware reports over recent commit history. Each is selected by a flag and rendered as `tabular` (default), `csv`, or `json` via `--format`. All four are derived from one in-process walk of the repository - there is no `exec("git")`, so the `git` binary does not need to be on `PATH`.
+In addition to counting the working tree, `scc` can run five git-aware reports over recent commit history. Each is selected by a flag and rendered as `tabular` (default), `csv`, or `json` via `--format`. All are derived from one in-process walk of the repository - there is no `exec("git")`, so the `git` binary does not need to be on `PATH`.
 
 > **Note:** these reports are **slower** than a normal `scc` run. They walk the repository history (one diff per commit using pure-Go Myers diff via [go-git](https://github.com/go-git/go-git)) instead of just counting the current working tree. Runtime scales with `--depth` (the commit window size, default `1000`; `0` means entire history). On large repositories with deep history, expect runtimes measured in seconds to minutes rather than the millisecond-scale you get from a plain `scc` run. Use `--depth` to bound the window.
 
@@ -844,6 +846,7 @@ When no report flag is set, `scc` behaves exactly as today, these flags are stri
 | Flag | Report | Answers |
 |---|---|---|
 | `--hotspots` | Hotspots | Which files are defect-prone - high complexity × high churn. |
+| `--coupling` / `--coupling-for FILE` | Change coupling | Which files change together - hidden dependencies and blast radius. |
 | `--by-author` | Author rollup | Bus factor - who last-touched the surviving code. |
 | `--by-author --timeline` | Author timeline | How each author's activity rises and falls over time. |
 | `--timeline` | Languages over time | How the language mix shifts - rewrites, migrations. |
@@ -857,7 +860,7 @@ Shared flags for these reports:
 | `-w, --wide` | - | 109-column variant of any report (extra columns where applicable). |
 | `--no-fold-authors` | off | Disable the name + email-domain identity folding fallback applied after `.mailmap`. |
 
-`--hotspots` is mutually exclusive with `--by-author` / `--timeline`; combining them is an error. With `--by-author` set, `--timeline` switches from the author rollup to the author timeline. Alone, `--timeline` renders the languages timeline.
+Each report is standalone: `--hotspots`, `--coupling` (or `--coupling-for`), and `--by-author` / `--timeline` are mutually exclusive, and combining them is an error. `--coupling-for FILE` implies `--coupling`. With `--by-author` set, `--timeline` switches from the author rollup to the author timeline. Alone, `--timeline` renders the languages timeline.
 
 #### Hotspots - `--hotspots`
 
@@ -881,6 +884,46 @@ main.go                           Go     180       44    2,510       8     48.2
 
 Tabular output shows the top files (≈20). `--wide` adds a hotspot bar and an added-lines code-vs-comment split (`+Code%`). `--format csv|json` emits every file with a positive score along with the full per-file detail and window metadata.
 
+#### Change coupling - `--coupling` / `--coupling-for`
+
+Which files tend to change together in the same commit I.E. *temporal* coupling.
+Surfaces the "if you edit A you probably need to edit B" relationships. `Shared Commits` is how
+many commits touched both files; `Coupling` is the share of commits touching *either* file that
+touched *both*, so 100% means they never move apart. Pairs are ranked strongest first,
+and only pairs sharing at least 2 commits are reported.
+
+```text
+$ scc --coupling
+───────────────────────────────────────────────────────────────────────────────
+Change Coupling · last 1000 commits · 2019-07-24 → 2026-07-20
+───────────────────────────────────────────────────────────────────────────────
+File A                      File B                      Shared Commits Coupling
+───────────────────────────────────────────────────────────────────────────────
+languages.json              processor/constants.go                 196    67.6%
+LANGUAGES.md                languages.json                         166    61.3%
+LANGUAGES.md                processor/constants.go                 152    58.2%
+main.go                     processor/processor.go                  65    33.9%
+───────────────────────────────────────────────────────────────────────────────
+top 15 of 492 pairs · sharing ≥2 commits
+───────────────────────────────────────────────────────────────────────────────
+```
+
+`--coupling-for FILE` narrows to a single file's and what history says tends to move with it.
+
+```text
+$ scc --coupling-for processor/workers.go
+───────────────────────────────────────────────────────────────────────────────
+Change Coupling · last 1000 commits · 2019-07-24 → 2026-07-20
+───────────────────────────────────────────────────────────────────────────────
+Related File                                          Shared Commits   Coupling
+───────────────────────────────────────────────────────────────────────────────
+processor/structs.go                                              27      25.2%
+processor/workers_test.go                                         17      17.7%
+processor/processor.go                                            34      15.7%
+main.go                                                           23      13.7%
+───────────────────────────────────────────────────────────────────────────────
+```
+
 #### Author rollup - `--by-author`
 
 Bus factor and last-toucher attribution. Lines untouched in the window collect under the sentinel `(before window)` so percentages reconcile to 100%.
@@ -1591,7 +1634,7 @@ Add to your `claude_desktop_config.json`:
 
 #### Exposed Tools
 
-The MCP server exposes two tools:
+The MCP server exposes three tools:
 
 **`analyze`** - Count lines of code, comments, blanks and estimate complexity for a project directory or file.
 
@@ -1619,6 +1662,17 @@ Results are returned as JSON with per-language breakdown (files, lines, code, co
 
 Results are returned as JSON with the history window walked (depth, commit count, date range) and a per-file list (file, language, complexity, commits, lines changed, authors, code/comment churn, and a normalised 0–100 score). Requires `path` to be inside a git repository.
 
+**`coupling`** - Report change coupling from a git repository's history: files that historically change together. Has two modes, selected by whether `file` is set. With `file`, returns that file's blast radius - the other files that change together with it. Without `file`, returns the repo-wide all-pairs overview.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `path` | string | no | Directory inside the git repository to analyze. Defaults to current directory. |
+| `file` | string | no | Target file (as it appears at HEAD). Set it for the per-file blast-radius view; omit it for the repo-wide all-pairs report. |
+| `depth` | number | no | Maximum number of recent commits to walk. Default: `1000`. Set to `0` for unlimited. |
+| `limit` | number | no | Maximum rows to return, strongest first - coupled files in per-file mode, file pairs in all-pairs mode. Default: `50`. Set to `-1` for unlimited. |
+
+Results are returned as JSON with the history window walked. With `file`, each partner carries its shared-commit count and the directional probabilities `couple` (given you changed the target, how often the partner follows) and `reverse` (the other direction). Without `file`, each pair carries its shared-commit count and symmetric coupling degree. Requires `path` to be inside a git repository.
+
 ### Adding/Modifying Languages
 
 To add or modify a language you will need to edit the `languages.json` file in the root of the project, and then run `go generate` to build it into the application. You can then `go install` or `go build` as normal to produce the binary with your modifications.
 
@@ -454,6 +454,8 @@ func registerFlags(flags *pflag.FlagSet, b *flagBindings) {
 	flags.Float64Var(floatVar(&processor.LocomoTPS), "locomo-tps", 0, "LOCOMO output tokens per second (overrides preset)")
 	flags.Float64Var(floatVar(&processor.LocomoCyclesOverride), "locomo-cycles", 0, "override estimated LLM iteration cycles (default: calculated from complexity)")
 	flags.BoolVar(boolVar(&processor.Hotspots), "hotspots", false, "render the hotspots report (files ranked by complexity × change frequency over recent git history)")
+	flags.BoolVar(boolVar(&processor.Coupling), "coupling", false, "render the change-coupling report (file pairs that change together over recent git history)")
+	flags.StringVar(strVar(&processor.CouplingFor), "coupling-for", "", "blast-radius view: given a file path, show what tends to change with it over recent git history")
 	flags.BoolVar(boolVar(&processor.ByAuthor), "by-author", false, "render the author rollup report (bus factor and last-toucher attribution over recent git history)")
 	flags.IntVar(intVar(&processor.HistoryDepth), "depth", 1000, "commit window size for git history reports; 0 means entire history (large repos may be slow)")
 	flags.BoolVar(boolVar(&processor.Timeline), "timeline", false, "render an over-time view of recent git history; with --by-author runs the author timeline, alone runs the languages timeline")
 
@@ -110,6 +110,41 @@ Also returns the history window walked (depth, commit count, date range). Requir
 
 	mcpServer.AddTool(hotspotsTool, mcpHotspotsHandler)
 
+	couplingTool := mcp.NewTool("coupling",
+		mcp.WithDescription(`Return change-coupling from a git repository's history — files that historically change together. Has two modes, selected by whether the 'file' argument is set.
+
+WITH 'file' — the target file's "blast radius": the other files that change together with it. Use this before editing a file to discover what else you will likely need to read or change. For the target, returns each coupled file with:
+- file: path relative to the repo root
+- shared: number of commits that changed BOTH the target and this file
+- partnerCommits: this file's own commit count in the window
+- couple: P(this file changes | you changed the target), 0–100 — the blast-radius probability
+- reverse: P(target changes | this file changed), 0–100 — a large gap from couple marks a hub-style (asymmetric) link rather than a true peer coupling
+Partners are ranked by degree (highest first; base-rate corrected). Also returns the target's own commit count (targetCommits) and the history window walked.
+
+WITHOUT 'file' — the repo-wide all-pairs overview: every file pair that changes together, strongest first. For each pair, returns:
+- fileA, fileB: the two coupled paths, relative to the repo root
+- shared: number of commits that changed BOTH files
+- commitsA, commitsB: each file's own commit count in the window
+- degree: symmetric coupling ratio shared/(commitsA+commitsB−shared), 0–100
+Pairs are ranked strongest first (most shared commits). Also returns the history window walked.
+
+Requires path to be inside a git repository.`),
+		mcp.WithString("file",
+			mcp.Description("Optional target file path (relative to the repo, as it appears at HEAD). Set it for the per-file blast-radius view; omit it for the repo-wide all-pairs report."),
+		),
+		mcp.WithString("path",
+			mcp.Description("Directory inside the git repository to analyze. Defaults to current directory."),
+		),
+		mcp.WithNumber("depth",
+			mcp.Description("Maximum number of recent commits to walk. Defaults to 1000. Set to 0 for unlimited (slower on large repos)."),
+		),
+		mcp.WithNumber("limit",
+			mcp.Description("Maximum rows to return, strongest first — coupled files in per-file mode, file pairs in all-pairs mode. Defaults to 50. Set to -1 for unlimited."),
+		),
+	)
+
+	mcpServer.AddTool(couplingTool, mcpCouplingHandler)
+
 	errLogger := log.New(os.Stderr, "scc-mcp: ", log.LstdFlags)
 	if err := server.ServeStdio(mcpServer, server.WithErrorLogger(errLogger)); err != nil {
 		_, _ = fmt.Fprintf(os.Stderr, "scc-mcp: server error: %v\n", err)
@@ -451,6 +486,64 @@ func mcpHotspotsHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.
 	return mcp.NewToolResultText(out), nil
 }
 
+func mcpCouplingHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+	args := request.GetArguments()
+
+	target, _ := args["file"].(string)
+
+	path := "."
+	if p, ok := args["path"].(string); ok && p != "" {
+		path = p
+	}
+
+	absPath, err := filepath.Abs(path)
+	if err != nil {
+		return mcp.NewToolResultError(fmt.Sprintf("invalid path: %v", err)), nil
+	}
+
+	if _, err := os.Stat(absPath); err != nil {
+		return mcp.NewToolResultError(fmt.Sprintf("path cannot be accessed: %s: %v", absPath, err)), nil
+	}
+
+	// Serialize access to processor globals so concurrent MCP requests don't
+	// race on shared state.
+	mcpMu.Lock()
+	defer mcpMu.Unlock()
+
+	processor.HistoryDepth = 1000
+	if d, ok := args["depth"].(float64); ok {
+		if d < 0 {
+			d = 0
+		}
+		processor.HistoryDepth = int(d)
+	}
+
+	fileLimit := 50
+	if l, ok := args["limit"].(float64); ok {
+		if l < 0 {
+			fileLimit = 0
+		} else {
+			fileLimit = int(l)
+		}
+	}
+
+	processor.ProcessConstants()
+	processor.ConfigureLazy(true)
+
+	// file set → per-file blast radius; file omitted → repo-wide all-pairs.
+	var out string
+	if target != "" {
+		out, err = processor.CouplingForJSONReport(absPath, target, fileLimit)
+	} else {
+		out, err = processor.CouplingJSONReport(absPath, fileLimit)
+	}
+	if err != nil {
+		return mcp.NewToolResultError(fmt.Sprintf("coupling analysis failed: %v", err)), nil
+	}
+
+	return mcp.NewToolResultText(out), nil
+}
+
 func jsonMarshal(v any) ([]byte, error) {
 	return json.MarshalIndent(v, "", "  ")
 }