Ai Repository Maps: Token-Cheap Overviews of Huge Monorepos

// repomap/types.ts
export type MapNode = {
  id: string;              // @acme/payments
  kind: "package" | "app" | "lib";
  path: string;
  exports: string[];       // public API names only
  owner: string;
  deps: string[];          // workspace deps
  hot?: boolean;           // touched in last 14d deploys
};

export type RepoMap = {
  sha: string;
  generatedAt: string;
  nodes: MapNode[];
  edges: { from: string; to: string }[];
};

# ✅ Generate on merge (CI artifact)
node scripts/build-repomap.mjs --out .repomap/map.json --max-exports 40

// tools/repomap.ts
export function l0(map: RepoMap, budgetTokens = 1500): string {
  // compact: id, owner, deps count, hot flag — no file lists
  return renderCompact(map.nodes, budgetTokens);
}

export function zoom(map: RepoMap, packageId: string): string {
  const n = map.nodes.find((x) => x.id === packageId);
  if (!n) return "UNKNOWN_PACKAGE";
  // ✅ exports + path + owner only; agent must open files via read tool
  return JSON.stringify(n, null, 2);
}

# scripts/repomap_validate.py
def validate(map_path: str, git_sha: str):
    m = json.load(open(map_path))
    assert m["sha"] == git_sha, "stale_map"
    orphan = [n for n in m["nodes"] if not n.get("owner")]
    assert not orphan, f"unowned:{orphan[:5]}"  # ✅ fail CI