perf: improve git I/O operation management

.github/linters/.cspell.json

@@ -102,6 +102,7 @@
         "omnistudio",
         "oxsecurity",
         "packageable",
+        "pathspec",
         "parens",
         "pastsha",
         "permissionset",

.github/workflows/on-pull-request.yml

@@ -65,7 +65,7 @@ jobs:
         uses: ./.github/actions/install
 
       - name: Check outdated dependencies
-        run: npm outdated
+        run: npm outdated --omit=dev
 
       - name: Check unused dependencies
         run: npm run lint:dependencies

DESIGN.md

@@ -360,7 +360,7 @@ flowchart TD
 
 **Collectors** (`isCollector = true`) run first via `collectAll()`. They produce additional `HandlerResult` data that gets merged into the main result:
 
-- **FlowTranslationProcessor**: when Flows are being deployed, scans all `.translation-meta.xml` files in the repo for `flowDefinitions` elements matching deployed flows. Produces pruned translation files as computed content.
+- **FlowTranslationProcessor**: when Flows are being deployed, uses `git grep` with pathspec globs (`<source>/*<extension><metaFileSuffix>`) to find `.translation-meta.xml` files containing `flowDefinitions` elements matching deployed flows. This avoids requiring the tree index. Produces pruned translation files as computed content.
 - **IncludeProcessor**: handles `--include` and `--include-destructive` flags. Lists all files in source directories, filters through include patterns, then processes matching lines through `DiffLineInterpreter` as synthetic additions/deletions.
 
 **Processors** (`isCollector = false`) run last via `executeRemaining()`:
@@ -373,13 +373,14 @@ Each processor is wrapped in error isolation — failures produce warnings rathe
 
 ## Stage 6: I/O Execution
 
-**Entry**: `IOExecutor.execute(copies)` (`src/service/ioExecutor.ts`)
+**Entry**: `IOExecutor.execute(copies)` (`src/adapter/ioExecutor.ts`)
 
-Executes the accumulated copy operations with concurrency bounded by `getConcurrencyThreshold()`. Two operation kinds:
+Executes the accumulated copy operations with concurrency bounded by `getConcurrencyThreshold()`. Three operation kinds:
 
 | Kind              | Description                                                                                                        |
 | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `GitCopy`         | Reads a file from a specific git revision via `git show <rev>:<path>` and writes it to the output directory        |
+| `GitCopy`         | Reads a single file from a specific git revision via the batch `git cat-file` process and writes it to the output directory. Does not require the tree index. |
+| `GitDirCopy`      | Enumerates all files under a directory path via `getFilesPath` (requires tree index), then copies each file via `git cat-file`. Used by handlers that need to copy entire directories (e.g., `ContainedDecomposedHandler` for decomposed PermissionSet holder folders). Executed serially because the outer `execute()` already parallelizes across operations. |
 | `ComputedContent` | Writes a string (typically pruned XML from InFile/ObjectTranslation handlers) directly to the output directory      |
 
 `GitAdapter.getBufferContent()` handles LFS detection: if the buffer starts with an LFS pointer signature, it reads the actual object from the local LFS cache instead.
@@ -427,7 +428,15 @@ Logger.debug(lazy`result: ${() => JSON.stringify(largeObject)}`)
 
 ### Git Adapter
 
-`GitAdapter` (`src/adapter/GitAdapter.ts`) wraps `simple-git` with a singleton pattern keyed by `Config` identity. It caches `pathExists` and `ls-tree` results per instance to avoid redundant git operations.
+`GitAdapter` (`src/adapter/GitAdapter.ts`) wraps `simple-git` with a singleton pattern keyed by `Config` identity. It minimizes git subprocess spawns via two strategies:
+
+**Tree index**: The tree index is a `Set<string>` of file paths per revision, populated exclusively by `preBuildTreeIndex(revision, scopePaths)` in `src/main.ts`. It serves `pathExists`, `getFilesPath`, and `listDirAtRevision` lookups without additional subprocess calls — if no index was pre-built for a revision, these methods return empty results. The index is **scoped** to reduce heap pressure: `preBuildTreeIndex` runs `git ls-tree --name-only -r <revision> -- <path1> <path2> ...` to index only the metadata directories that handlers actually need. Both revisions (`config.to` and `config.from`) are indexed in parallel via `Promise.all`. Scope computation (`computeTreeIndexScope` in `src/utils/treeIndexScope.ts`) analyzes diff lines against the metadata registry to determine which type directories require tree-index lookups — only types using `InResource`, `InFolder`, `ReportingFolder`, `InBundle`, `Lwc`, `CustomObject`, `ContainedDecomposed`, or `MetadataBoundaryResolver` deep-path resolution need the index. When `--include` or `--include-destructive` is set, the scope defaults to `config.source` since the include processor may touch any type. When `generateDelta` is false, the tree index is never built.
+
+**Batch cat-file**: `GitBatchCatFile` (`src/adapter/gitBatchCatFile.ts`) spawns a single long-lived `git cat-file --batch` child process per adapter instance. File content reads write `<revision>:<path>\n` to stdin and parse the binary response from stdout using a FIFO queue. This replaces individual `git show` subprocess spawns.
+
+Lifecycle: `GitAdapter.closeAll()` terminates all batch processes and clears the singleton instances map. It is called in a `finally` block in `src/main.ts` to prevent orphaned child processes on both success and error paths. If the `git cat-file` process exits unexpectedly, a `close` event handler rejects all pending promises to prevent hangs.
+
+**Memory note**: The batch cat-file process buffers each blob's content entirely in memory before resolving. There is no upper bound on individual blob size — repositories with very large binary blobs (multi-GB) could cause high memory consumption. This is acceptable because SGD operates on trusted repositories and the previous `git show` implementation had the same characteristic.
 
 ---
 
@@ -488,7 +497,7 @@ Universal handler/processor output:
 | Field | Type | Description |
 | ----- | ---- | ----------- |
 | `manifests` | `ManifestElement[]` | Entries for package.xml or destructiveChanges.xml |
-| `copies` | `CopyOperation[]` | `GitCopy` or `ComputedContent` operations |
+| `copies` | `CopyOperation[]` | `GitCopy`, `GitDirCopy`, or `ComputedContent` operations |
 | `warnings` | `Error[]` | Non-fatal warnings |
 
 ### Metadata (`src/schemas/metadata.ts`)

__tests__/functional/main.test.ts

@@ -10,6 +10,24 @@ import {
   ManifestTarget,
 } from '../../src/types/handlerResult'
 
+jest.mock('../../src/utils/LoggingService')
+
+const mockPreBuildTreeIndex = jest.fn()
+jest.mock('../../src/adapter/GitAdapter', () => ({
+  default: {
+    getInstance: jest.fn(() => ({
+      preBuildTreeIndex: mockPreBuildTreeIndex,
+    })),
+    closeAll: jest.fn(),
+  },
+}))
+
+const mockComputeTreeIndexScope = jest.fn()
+jest.mock('../../src/utils/treeIndexScope', () => ({
+  computeTreeIndexScope: (...args: unknown[]) =>
+    mockComputeTreeIndexScope(...args),
+}))
+
 const mockValidateConfig = jest.fn()
 jest.mock('../../src/utils/configValidator', () => {
   // biome-ignore lint/suspicious/noExplicitAny: let TS know it is an object
@@ -70,7 +88,7 @@ jest.mock('../../src/post-processor/postProcessorManager', () => {
 })
 
 const mockExecute = jest.fn()
-jest.mock('../../src/service/ioExecutor', () => {
+jest.mock('../../src/adapter/ioExecutor', () => {
   return {
     default: jest.fn().mockImplementation(() => {
       return {
@@ -85,6 +103,7 @@ beforeEach(() => {
   mockProcess.mockResolvedValue(emptyResult())
   mockCollectAll.mockResolvedValue(emptyResult())
   mockGetLines.mockResolvedValue([] as never)
+  mockComputeTreeIndexScope.mockReturnValue(new Set())
 })
 
 describe('external library inclusion', () => {
@@ -218,4 +237,96 @@ describe('external library inclusion', () => {
       expect(result.warnings).toContain(postWarning)
     })
   })
+
+  describe('tree index scoping', () => {
+    it('Given generateDelta is false, When sgd runs, Then preBuildTreeIndex is not called', async () => {
+      // Act
+      await sgd({ generateDelta: false } as Config)
+
+      // Assert
+      expect(mockPreBuildTreeIndex).not.toHaveBeenCalled()
+    })
+
+    it('Given generateDelta is true with include set, When sgd runs, Then preBuildTreeIndex is called with config.source', async () => {
+      // Arrange
+      const sut = {
+        generateDelta: true,
+        include: 'include.txt',
+        to: 'HEAD',
+        from: 'HEAD~1',
+        source: ['force-app'],
+      } as Config
+
+      // Act
+      await sgd(sut)
+
+      // Assert
+      expect(mockPreBuildTreeIndex).toHaveBeenCalledWith('HEAD', ['force-app'])
+      expect(mockPreBuildTreeIndex).toHaveBeenCalledWith('HEAD~1', [
+        'force-app',
+      ])
+      expect(mockComputeTreeIndexScope).not.toHaveBeenCalled()
+    })
+
+    it('Given generateDelta is true with includeDestructive set, When sgd runs, Then preBuildTreeIndex is called with config.source', async () => {
+      // Arrange
+      const sut = {
+        generateDelta: true,
+        includeDestructive: 'destructive.txt',
+        to: 'HEAD',
+        from: 'HEAD~1',
+        source: ['src'],
+      } as Config
+
+      // Act
+      await sgd(sut)
+
+      // Assert
+      expect(mockPreBuildTreeIndex).toHaveBeenCalledWith('HEAD', ['src'])
+      expect(mockPreBuildTreeIndex).toHaveBeenCalledWith('HEAD~1', ['src'])
+    })
+
+    it('Given generateDelta is true with computed scope paths, When sgd runs, Then preBuildTreeIndex is called with scope paths', async () => {
+      // Arrange
+      mockComputeTreeIndexScope.mockReturnValueOnce(
+        new Set(['force-app/main/default/classes'])
+      )
+      const sut = {
+        generateDelta: true,
+        to: 'HEAD',
+        from: 'HEAD~1',
+        source: ['force-app'],
+      } as Config
+
+      // Act
+      await sgd(sut)
+
+      // Assert
+      expect(mockComputeTreeIndexScope).toHaveBeenCalled()
+      expect(mockPreBuildTreeIndex).toHaveBeenCalledWith('HEAD', [
+        'force-app/main/default/classes',
+      ])
+      expect(mockPreBuildTreeIndex).toHaveBeenCalledWith('HEAD~1', [
+        'force-app/main/default/classes',
+      ])
+    })
+
+    it('Given generateDelta is true with empty scope paths, When sgd runs, Then preBuildTreeIndex is not called', async () => {
+      // Arrange
+      mockComputeTreeIndexScope.mockReturnValueOnce(new Set())
+      const sut = {
+        generateDelta: true,
+        to: 'HEAD',
+        from: 'HEAD~1',
+        source: ['force-app'],
+      } as Config
+
+      // Act
+      await sgd(sut)
+
+      // Assert
+      expect(mockComputeTreeIndexScope).toHaveBeenCalled()
+      expect(mockPreBuildTreeIndex).not.toHaveBeenCalled()
+    })
+  })
 })