feat: pull aztec-packages docs from next branch via sparsePathOverrides

Add sparsePathOverrides to RepoConfig so specific sparse paths can be
checked out from a different branch after the tag-based clone. This
keeps docs/docs on the latest next branch while other paths stay pinned
to the version tag.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: critesjosh

src/repos/config.ts

@@ -22,6 +22,8 @@ export interface RepoConfig {
     code?: string[];
     docs?: string[];
   };
+  /** Override specific sparse paths to come from a different branch instead of the tag */
+  sparsePathOverrides?: { paths: string[]; branch: string }[];
 }
 
 /** Default Aztec version (tag) to use - can be overridden via AZTEC_DEFAULT_VERSION env var */
@@ -43,6 +45,9 @@ const BASE_REPOS: Omit<RepoConfig, "tag">[] = [
       "boxes",
       "playground",
     ],
+    sparsePathOverrides: [
+      { paths: ["docs/docs"], branch: "next" },
+    ],
     description: "Main Aztec monorepo - documentation, aztec-nr framework, and reference contracts",
     searchPatterns: {
       code: ["*.nr", "*.ts"],

src/utils/git.ts

@@ -90,6 +90,14 @@ export async function cloneRepo(
       await repoGit.raw(["sparse-checkout", "set", ...config.sparse]);
       await repoGit.fetch(["--depth=1", "origin", `refs/tags/${config.tag}:refs/tags/${config.tag}`]);
       await repoGit.checkout(config.tag);
+
+      // Apply sparse path overrides from different branches
+      if (config.sparsePathOverrides) {
+        for (const override of config.sparsePathOverrides) {
+          await repoGit.fetch(["--depth=1", "origin", override.branch]);
+          await repoGit.checkout([`origin/${override.branch}`, "--", ...override.paths]);
+        }
+      }
     } else {
       await git.clone(config.url, repoPath, [
         "--filter=blob:none",

tests/repos/config.test.ts

@@ -26,6 +26,14 @@ describe("AZTEC_REPOS", () => {
     expect(noir!.sparse!.length).toBeGreaterThan(0);
   });
 
+  it("aztec-packages has sparsePathOverrides for docs/docs on next branch", () => {
+    const ap = AZTEC_REPOS.find((r) => r.name === "aztec-packages");
+    expect(ap?.sparse).toContain("docs/docs");
+    expect(ap?.sparsePathOverrides).toEqual([
+      { paths: ["docs/docs"], branch: "next" },
+    ]);
+  });
+
   it('noir and noir-examples have branch: "master"', () => {
     const noir = AZTEC_REPOS.find((r) => r.name === "noir");
     const noirExamples = AZTEC_REPOS.find((r) => r.name === "noir-examples");

tests/utils/git.test.ts

@@ -146,6 +146,36 @@ describe("cloneRepo", () => {
     expect(mockGitInstance.checkout).toHaveBeenCalledWith("v1.0.0");
   });
 
+  it("sparse + tag + sparsePathOverrides: fetches override branch and checks out paths", async () => {
+    const overrideConfig: RepoConfig = {
+      ...sparseConfig,
+      sparsePathOverrides: [{ paths: ["docs/docs"], branch: "next" }],
+    };
+    mockExistsSync.mockReturnValue(false);
+    mockGitInstance.clone.mockResolvedValue(undefined);
+    mockGitInstance.raw.mockResolvedValue(undefined);
+    mockGitInstance.fetch.mockResolvedValue(undefined);
+    mockGitInstance.checkout.mockResolvedValue(undefined);
+
+    const result = await cloneRepo(overrideConfig);
+    expect(result).toContain("Cloned aztec-packages");
+
+    // Normal tag checkout happens first
+    expect(mockGitInstance.checkout).toHaveBeenCalledWith("v1.0.0");
+
+    // Then override: fetch the branch and checkout paths from it
+    expect(mockGitInstance.fetch).toHaveBeenCalledWith([
+      "--depth=1",
+      "origin",
+      "next",
+    ]);
+    expect(mockGitInstance.checkout).toHaveBeenCalledWith([
+      "origin/next",
+      "--",
+      "docs/docs",
+    ]);
+  });
+
   it("sparse + commit: clones with sparse flags, fetches commit", async () => {
     const commitConfig: RepoConfig = {
       ...sparseConfig,