feat(config): let one config name a whole multi-repo cluster (#156)

Cross-repo linking was reachable only from an MCP session: `append` is a
generate_snapshot tool parameter and both CLIs hardcoded false, so a CI job or a
developer not driving an agent saw only the single-repo subset — no service nodes,
no cross-repo edges, no coverage_report, no unused-routes.

A config may now name the cluster, and one --generate run indexes it, first
repository fresh and the rest appended:

  repos:
    - ../api
    - ../web
    - ../sdk

Entries resolve against the config file's own directory rather than the working
directory, so a checked-in cluster config means the same thing on a laptop and in
CI; `repo:` keeps its cwd-relative behaviour. Order is semantic and duplicates are
dropped — a repository listed twice would be indexed twice, the second pass
appending a duplicate of every fact the first contributed.

--explain takes a cluster config too. Its positional argument was previously always
a repository path, so `--explain cluster.yaml` analysed the YAML file as if it were
a repo. A repository is a directory and a config is a file, which separates them
without a flag.

Author: dejo1307

ARCHITECTURE.md

@@ -664,6 +664,11 @@ The config file is **optional**. Every field has a built-in default (see `config
 
 ```yaml
 repo: "."
+# …or name a whole cluster instead, resolved relative to THIS file:
+# repos:
+#   - ../api
+#   - ../web
+#   - ../sdk
 ignore:
   - "vendor/**"
   - "node_modules/**"
@@ -711,7 +716,8 @@ The bundled [`mcp-arch.yaml`](mcp-arch.yaml) ships a much fuller `ignore` list (
 
 | Field | Description | Default |
 |-------|-------------|---------|
-| `repo` | Repository root path | `"."` |
+| `repo` | Repository root path, relative to the **working directory** | `"."` |
+| `repos` | Ordered list of repository roots forming a multi-repo cluster; supersedes `repo`. One `--generate` run indexes them all (the first fresh, the rest appended), producing the service nodes and cross-repo edges a single-repo snapshot cannot have. Entries resolve relative to the **config file's own directory**, so a checked-in cluster config means the same thing wherever it is run from. Order is semantic; duplicates are dropped | *(unset)* |
 | `ignore` | Glob patterns for files/dirs to skip | vendor, node_modules, .git, tests, build dirs, minified JS (`*.min.js`/`*.bundle.js`), docs, config data, … |
 | `extractors` | Enabled extractors | `["cpp", "go", "grpc", "java", "kotlin", "openapi", "php", "python", "typescript", "swift", "ruby", "rust"]` |
 | `explainers` | Enabled explainers | `["cycles", "layers", "crossrepo", "coverage", "unused-routes", "god-class", "hotspots", "dependency-depth", "exported-surface", "complexity-outliers"]` |

README.md

@@ -433,6 +433,22 @@ enola --generate [config_path]   # config_path is optional; defaults to mcp-arch
 
 Artifacts are written to the configured `output.dir` (default `.enola/`). The config file is optional - see **[ARCHITECTURE.md → Configuration](ARCHITECTURE.md#configuration)** for the full field reference and defaults.
 
+**Indexing a whole cluster in one command.** Cross-repo linking needs several repositories in one graph. Name them with `repos:` and a single run indexes them all - the first fresh, the rest appended - producing the service nodes, cross-repo edges, `coverage_report` and unused-route findings that a single-repo snapshot cannot have:
+
+```yaml
+# ci/cluster.yaml
+repos:
+  - ../api
+  - ../web
+  - ../sdk
+```
+
+```bash
+enola --generate ci/cluster.yaml
+```
+
+Entries resolve **relative to the config file**, not to your working directory, so a cluster config can be checked in and means the same thing on a laptop and in CI. (`repo:` is unchanged: a single repository, relative to the working directory.) Order matters - the first entry resets the graph and the rest are added to it.
+
 ---
 
 ## Explain a repository at a glance
@@ -453,8 +469,13 @@ enola --explain
 
 # Analyze a specific repository path
 enola --explain /path/to/repo
+
+# Report over a whole cluster, from a config that names it with `repos:`
+enola --explain ci/cluster.yaml
 ```
 
+The argument is a **repository** when it is a directory and a **config file** when it is a file, so both forms work without a flag to tell them apart.
+
 **The report covers nine sections:**
 - **Overview** - path, analysis time, active languages, total fact count
 - **Architectural kinds** - counts of modules, symbols, routes, storage, dependencies, services
@@ -589,8 +610,8 @@ Run `enola --help` for the full text. With no flags, enola starts the MCP server
 
 | Flag | What it does |
 |------|--------------|
-| `--generate [config_path]` | Generate a snapshot and exit - no MCP server. Artifacts go to `output.dir` (default `.enola/`). |
-| `--explain [repo_path]` | Print the statistics report above and exit. Read-only: nothing is written to `.enola/`. |
+| `--generate [config_path]` | Generate a snapshot and exit - no MCP server. Artifacts go to `output.dir` (default `.enola/`). With `repos:` in the config, indexes the whole cluster in one run. |
+| `--explain [repo_path\|config_path]` | Print the statistics report above and exit. Read-only: nothing is written to `.enola/`. A directory is a repository; a file is a config, so a `repos:` config reports over the whole cluster. |
 | `--list` | List the MCP tools this build serves, with one-line summaries. |
 | `--status` | List every enola server running right now - PID, repos, uptime, calls, dashboard URL - plus per-tool call counts and an estimate of the reconstruction those calls saved, in time and tokens. |
 | `--status --all` | The same usage, broken down per repository. |

cmd/enola/main.go

@@ -11,6 +11,7 @@ import (
 	"time"
 
 	"github.com/enola-labs/enola/internal/config"
+	"github.com/enola-labs/enola/internal/facts"
 	"github.com/enola-labs/enola/internal/upgrade"
 	"github.com/enola-labs/enola/internal/version"
 	"github.com/enola-labs/enola/pkg/bootstrap"
@@ -68,10 +69,16 @@ func main() {
 			noDashboard = true
 		default:
 			// In --explain mode the positional argument is the repository path;
-			// otherwise it is the config file path.
-			if explainMode {
+			// otherwise it is the config file path. A repository is a directory and
+			// a config is a file, so `--explain cluster.yaml` is unambiguous — and
+			// without this it would analyse the YAML file as if it were a repo and
+			// report on nothing.
+			switch {
+			case explainMode && isDirectory(arg):
 				explainRepo = arg
-			} else {
+			case explainMode:
+				cfgPath = arg
+			default:
 				cfgPath = arg
 			}
 		}
@@ -101,18 +108,24 @@ func main() {
 	}
 
 	if generateMode {
-		repoPath, err := filepath.Abs(cfg.Repo)
+		repoPaths, err := cfg.RepoPaths()
 		if err != nil {
 			log.Fatalf("failed to resolve repo path: %v", err)
 		}
 
-		snapshot, err := eng.GenerateSnapshot(ctx, repoPath, false)
-		if err != nil {
-			log.Fatalf("snapshot generation failed: %v", err)
-		}
-
-		if err := eng.WriteArtifacts(repoPath); err != nil {
-			log.Fatalf("failed to write artifacts: %v", err)
+		var snapshot *facts.Snapshot
+		for i, repoPath := range repoPaths {
+			// The first repository resets the store; the rest append to it, which is
+			// what makes one process produce one linked graph.
+			snapshot, err = eng.GenerateSnapshot(ctx, repoPath, i > 0)
+			if err != nil {
+				log.Fatalf("snapshot generation failed for %s: %v", repoPath, err)
+			}
+			// In multi-repo mode WriteArtifacts writes the whole store to each
+			// repo's output dir, matching what the MCP server does per generate.
+			if err := eng.WriteArtifacts(repoPath); err != nil {
+				log.Fatalf("failed to write artifacts for %s: %v", repoPath, err)
+			}
 		}
 
 		// Refresh the graph-wide receipt at ~/.enola/receipt.json. Non-fatal: a
@@ -122,12 +135,19 @@ func main() {
 		}
 
 		fmt.Fprintf(os.Stderr, "\nSnapshot complete:\n")
-		fmt.Fprintf(os.Stderr, "  Repository:  %s\n", snapshot.Meta.RepoPath)
+		if len(repoPaths) > 1 {
+			fmt.Fprintf(os.Stderr, "  Repositories: %d\n", len(repoPaths))
+			for _, p := range repoPaths {
+				fmt.Fprintf(os.Stderr, "    - %s\n", p)
+			}
+		} else {
+			fmt.Fprintf(os.Stderr, "  Repository:  %s\n", snapshot.Meta.RepoPath)
+		}
 		fmt.Fprintf(os.Stderr, "  Facts:       %d\n", snapshot.Meta.FactCount)
 		fmt.Fprintf(os.Stderr, "  Insights:    %d\n", snapshot.Meta.InsightCount)
 		fmt.Fprintf(os.Stderr, "  Artifacts:   %d\n", len(snapshot.Artifacts))
 		fmt.Fprintf(os.Stderr, "  Duration:    %s\n", snapshot.Meta.Duration)
-		fmt.Fprintf(os.Stderr, "  Output:      %s\n", filepath.Join(repoPath, cfg.Output.Dir))
+		fmt.Fprintf(os.Stderr, "  Output:      %s\n", filepath.Join(repoPaths[len(repoPaths)-1], cfg.Output.Dir))
 		os.Exit(0)
 	}
 
@@ -216,23 +236,40 @@ func helpSpec() cli.HelpSpec {
 // runExplain indexes the given repository (defaulting to the configured repo)
 // and prints a human-readable statistical summary to stdout.
 func runExplain(ctx context.Context, eng *bootstrap.Engine, cfg *config.Config, repoArg string) {
-	repo := repoArg
-	if repo == "" {
-		repo = cfg.Repo
-	}
-	repoPath, err := filepath.Abs(repo)
-	if err != nil {
-		log.Fatalf("failed to resolve repo path: %v", err)
+	// A positional argument names one repository and overrides the config; with no
+	// argument the config decides, which is what lets `repos:` produce a report over
+	// the whole cluster rather than its first member.
+	var repoPaths []string
+	if repoArg != "" {
+		abs, err := filepath.Abs(repoArg)
+		if err != nil {
+			log.Fatalf("failed to resolve repo path: %v", err)
+		}
+		repoPaths = []string{abs}
+	} else {
+		var err error
+		if repoPaths, err = cfg.RepoPaths(); err != nil {
+			log.Fatalf("failed to resolve repo path: %v", err)
+		}
 	}
 
-	fmt.Fprintf(os.Stderr, "Analyzing %s …\n", repoPath)
 	// --explain is a read-only, no-artifacts mode: reuse a cache if one exists,
 	// but never write to .enola.
 	eng.SetPersistCache(false)
-	if _, err := eng.GenerateSnapshot(ctx, repoPath, false); err != nil {
-		log.Fatalf("snapshot generation failed: %v", err)
+	for i, repoPath := range repoPaths {
+		fmt.Fprintf(os.Stderr, "Analyzing %s …\n", repoPath)
+		if _, err := eng.GenerateSnapshot(ctx, repoPath, i > 0); err != nil {
+			log.Fatalf("snapshot generation failed for %s: %v", repoPath, err)
+		}
 	}
 
 	report := explain.Compute(eng)
 	fmt.Print(report.Render())
 }
+
+// isDirectory reports whether path names an existing directory. Used to tell a
+// repository argument from a config-file argument.
+func isDirectory(path string) bool {
+	fi, err := os.Stat(path)
+	return err == nil && fi.IsDir()
+}

examples/multi-repo.yaml

@@ -1,25 +1,40 @@
 # enola configuration for cross-repo analysis.
 #
 # This config enables all extractors so it works regardless of which
-# languages each repository uses. Use append mode to build a combined
-# snapshot across multiple repositories.
+# languages each repository uses. There are two ways to build the combined
+# snapshot; they produce the same graph.
 #
-# Workflow:
-#   1. Generate the first repo:
-#      > "Generate an architectural snapshot of /path/to/ruby-monolith"
+# A. Name the cluster here, and index it in one command:
 #
-#   2. Append additional repos:
-#      > "Generate a snapshot of /path/to/go-service with append mode"
+#      enola --generate examples/multi-repo.yaml
 #
-#   3. Query across repos:
+#    Uncomment `repos:` below. Entries resolve relative to THIS FILE, not to
+#    your working directory, so the config can be checked in and means the
+#    same thing on a laptop and in CI. Order is semantic: the first entry
+#    resets the graph and the rest are added to it.
+#
+# B. Drive it from your agent, one repo at a time:
+#
+#      1. > "Generate an architectural snapshot of /path/to/ruby-monolith"
+#      2. > "Generate a snapshot of /path/to/go-service with append mode"
+#
+# Then query across repos:
 #      > "Query all route facts"                      (all repos)
 #      > "Query all symbols in go-service"             (single repo)
 #
 # Each repo is tagged with a label derived from its directory name
 # (e.g. /path/to/go-service -> "go-service"). File paths in the
 # fact store are prefixed with the repo label in multi-repo mode.
+#
+# Cross-repo edges, `coverage_report` and unused-route findings only exist
+# with two or more repos loaded — which is what either route above gives you.
 
 repo: "."
+
+# repos:
+#   - ../ruby-monolith
+#   - ../go-service
+#   - ../web-client
 ignore:
   # Dependencies and tooling
   - "vendor/**"

internal/config/config.go

@@ -3,13 +3,38 @@ package config
 import (
 	"fmt"
 	"os"
+	"path/filepath"
+	"strings"
 
 	"gopkg.in/yaml.v3"
 )
 
 // Config represents the mcp-arch.yaml configuration.
 type Config struct {
-	Repo       string       `yaml:"repo"`
+	Repo string `yaml:"repo"`
+
+	// Repos is the ordered list of repositories that form a multi-repo cluster.
+	// When set it supersedes Repo, and the whole cluster is indexed in one run —
+	// the first repository fresh, the rest appended.
+	//
+	// It exists because cross-repo linking was previously reachable only from an
+	// MCP session: `append` is a generate_snapshot tool parameter, and both CLIs
+	// hardcoded false, so a CI job or a developer not driving an agent could only
+	// ever see the single-repo subset (no service nodes, no cross-repo edges, no
+	// coverage_report, no unused-routes). Naming the cluster in the config also
+	// makes its composition a reviewable file rather than a property of the order
+	// somebody happened to issue tool calls in.
+	//
+	// Entries are resolved relative to the DIRECTORY OF THIS FILE, not the working
+	// directory, so a checked-in cluster config means the same thing wherever it is
+	// run from. (Repo keeps its historical cwd-relative behaviour.)
+	Repos []string `yaml:"repos"`
+
+	// SourcePath is the file this config was read from, or "" when the built-in
+	// defaults are in force. Not read from YAML — set by Load, and used to resolve
+	// Repos entries against the config's own directory.
+	SourcePath string `yaml:"-"`
+
 	Ignore     []string     `yaml:"ignore"`
 	TestGlobs  []string     `yaml:"test_globs"`
 	Extractors []string     `yaml:"extractors"`
@@ -202,6 +227,13 @@ func Load(path string) (*Config, error) {
 	if err := yaml.Unmarshal(data, cfg); err != nil {
 		return nil, fmt.Errorf("parsing config %s: %w", path, err)
 	}
+	// Recorded so Repos entries resolve against the config's own directory; see
+	// RepoPaths.
+	if abs, err := filepath.Abs(path); err == nil {
+		cfg.SourcePath = abs
+	} else {
+		cfg.SourcePath = path
+	}
 
 	// Ensure required defaults
 	if cfg.Output.Dir == "" {
@@ -214,6 +246,66 @@ func Load(path string) (*Config, error) {
 	return cfg, nil
 }
 
+// RepoPaths returns the absolute repository paths this run covers, in the order
+// they should be indexed: the first fresh, the rest appended.
+//
+// This is the single definition of "which repositories does this config describe",
+// so the CLI, --explain and any wrapper agree. Two resolution rules, and the
+// difference is deliberate:
+//
+//   - Repos entries resolve against the config file's own directory, because a
+//     cluster config is meant to be checked in and to mean the same thing wherever
+//     it is run from. With no config file (built-in defaults) there is no such
+//     directory, so they fall back to the working directory.
+//   - Repo resolves against the working directory, unchanged, because that is what
+//     `repo: "."` has always meant.
+//
+// Returns exactly one path when Repos is empty, so a single-repo caller needs no
+// special case.
+func (c *Config) RepoPaths() ([]string, error) {
+	if len(c.Repos) == 0 {
+		abs, err := filepath.Abs(c.Repo)
+		if err != nil {
+			return nil, fmt.Errorf("resolving repo %q: %w", c.Repo, err)
+		}
+		return []string{abs}, nil
+	}
+
+	base := ""
+	if c.SourcePath != "" {
+		base = filepath.Dir(c.SourcePath)
+	}
+	out := make([]string, 0, len(c.Repos))
+	seen := map[string]bool{}
+	for _, r := range c.Repos {
+		// Trimmed before the emptiness check: a whitespace-only entry is a YAML
+		// slip, and filepath.Abs would happily turn it into the working directory.
+		r = strings.TrimSpace(r)
+		if r == "" {
+			continue
+		}
+		p := r
+		if !filepath.IsAbs(p) && base != "" {
+			p = filepath.Join(base, p)
+		}
+		abs, err := filepath.Abs(p)
+		if err != nil {
+			return nil, fmt.Errorf("resolving repos entry %q: %w", r, err)
+		}
+		// A repository listed twice would be indexed twice, the second pass
+		// appending a duplicate of every fact it already contributed.
+		if seen[abs] {
+			continue
+		}
+		seen[abs] = true
+		out = append(out, abs)
+	}
+	if len(out) == 0 {
+		return nil, fmt.Errorf("repos is set but contains no usable paths")
+	}
+	return out, nil
+}
+
 // IsExtractorEnabled returns true if the named extractor is enabled.
 func (c *Config) IsExtractorEnabled(name string) bool {
 	return contains(c.Extractors, name)