refactor(code-index): extract scan execution without behavior changes

[WebMad]

Summary

Refs #1819; first narrowly scoped extraction split from #1821. This branch starts from upstream main and does not include the other behavior changes in #1821.

• Extract full/incremental scan execution, shared progress/error accumulation, missing-result checks and full-scan validation into code-index-scan-executor.ts.
• Keep startup guards, scan-mode selection, cancellation cleanup, watcher ownership/startup, completion persistence and destructive error cleanup in orchestrator.ts.
• Add focused executor coverage and orchestrator integration checks for operation ordering and cancellation cleanup.

Behavior preservation

• Incremental batch errors continue to be tolerated, including partial success. Changing this policy belongs to the separate safe-recovery PR.
• Full-scan failure thresholds, validation precedence and error messages are preserved, including the strict greater-than-10% threshold when batch errors exist.
• A scanner that returns after cancellation produces a cancellation result rather than a new exception. The existing normal-return cleanup path remains in the orchestrator, including retrying cache flush via its existing catch handler if the first flush fails.
• Scanner rejections propagate unchanged. Cancellation is checked before missing-result checks and validation.
• Existing watcher behavior, clear-index behavior, telemetry and completion-marker semantics are unchanged.

Deliberately excluded

Watcher restart/session fixes, run ownership and clearing serialization, draining active watcher writes, deletion-error propagation, incremental failure policy changes, and preservation of pre-existing points across failed retries remain separate work. This PR does not resolve or auto-close #1819 or the outstanding behavioral review requests on #1821.

Validation

• Complete code-index suite: 704 tests passed across 31 files.
• Changed-file ESLint with suppression pruning passed; suppression counts unchanged.
• Extension TypeScript no-emit check passed.
• Repository commit/push hooks: lint and type checks passed.
• Diff whitespace check passed.

Environment caveat: local Node 24.7.0 differs from the requested 22.23.1; CI validation is still required.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: Zoo-Code-Org/Zoo-Code/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 93b4246a-fab9-48b4-8456-2070cad13fcc

📥 Commits

Reviewing files that changed from the base of the PR and between d351a15 and d2c05e3.

📒 Files selected for processing (4)

• src/services/code-index/__tests__/code-index-scan-executor.spec.ts
• src/services/code-index/__tests__/orchestrator.spec.ts
• src/services/code-index/code-index-scan-executor.ts
• src/services/code-index/orchestrator.ts

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 2 remain after this review.

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (5)

Check persistence and lifecycle invariants: awaited atomic writes, rollback or explicit partial-failure behavior, cross-window state consistency, stale listeners/watchers, cancellation, idempotency, and safe restart/resume without lost or d...

⚙️ CodeRabbit configuration file

Files:

• src/services/code-index/__tests__/orchestrator.spec.ts
• src/services/code-index/orchestrator.ts
• src/services/code-index/__tests__/code-index-scan-executor.spec.ts
• src/services/code-index/code-index-scan-executor.ts

Require regression coverage at the lowest valid harness with behavior-focused assertions, including relevant negative, error, false/unset, and boundary cases.

⚙️ CodeRabbit configuration file

Files:

• src/services/code-index/__tests__/orchestrator.spec.ts
• src/services/code-index/__tests__/code-index-scan-executor.spec.ts

Check strict typing and exhaustive behavior across normal, boundary, error, cancellation, retry, and compatibility paths.

⚙️ CodeRabbit configuration file

Files:

• src/services/code-index/__tests__/orchestrator.spec.ts
• src/services/code-index/orchestrator.ts
• src/services/code-index/__tests__/code-index-scan-executor.spec.ts
• src/services/code-index/code-index-scan-executor.ts

Verify extension/webview contracts, cancellation and error propagation, VS Code lifecycle correctness, and behavior under retries and partial failure.

⚙️ CodeRabbit configuration file

Files:

• src/services/code-index/__tests__/orchestrator.spec.ts
• src/services/code-index/orchestrator.ts
• src/services/code-index/__tests__/code-index-scan-executor.spec.ts
• src/services/code-index/code-index-scan-executor.ts

Act as an adversarial second-opinion reviewer.

⚙️ CodeRabbit configuration file

Files:

• src/services/code-index/__tests__/orchestrator.spec.ts
• src/services/code-index/orchestrator.ts
• src/services/code-index/__tests__/code-index-scan-executor.spec.ts
• src/services/code-index/code-index-scan-executor.ts

🪛 GitHub Check: mutation-diff

src/services/code-index/code-index-scan-executor.ts

[warning] 55-55: Mutation test advisory
src/services/code-index/code-index-scan-executor.ts:55: 7 mutation test gaps; example: Survived StringLiteral mutant (replacement: ``). See the job summary for the complete list and resolution guidance.

---

[warning] 29-29: Mutation test advisory
src/services/code-index/code-index-scan-executor.ts:29: Survived StringLiteral mutant (replacement: ""). See the job summary for the complete list and resolution guidance.

---

[warning] 26-26: Mutation test advisory
src/services/code-index/code-index-scan-executor.ts:26: Survived StringLiteral mutant (replacement: ``). See the job summary for the complete list and resolution guidance.

---

[warning] 24-24: Mutation test advisory
src/services/code-index/code-index-scan-executor.ts:24: 4 mutation test gaps; example: Survived ConditionalExpression mutant (replacement: true). See the job summary for the complete list and resolution guidance.

---

[warning] 20-20: Mutation test advisory
src/services/code-index/code-index-scan-executor.ts:20: Survived StringLiteral mutant (replacement: ""). See the job summary for the complete list and resolution guidance.

---

[warning] 17-17: Mutation test advisory
src/services/code-index/code-index-scan-executor.ts:17: Survived StringLiteral mutant (replacement: ""). See the job summary for the complete list and resolution guidance.

🔇 Additional comments (4)

src/services/code-index/__tests__/code-index-scan-executor.spec.ts (1)

1-149: LGTM!

src/services/code-index/orchestrator.ts (1)

20-32: LGTM!

Also applies to: 152-152, 166-166

src/services/code-index/__tests__/orchestrator.spec.ts (1)

110-174: LGTM!

src/services/code-index/code-index-scan-executor.ts (1)

83-100: 🎯 Functional Correctness

The validation precedence is preserved. The old orchestrator used the same three conditions in the same order, so this comment identifies no behavior change.

---

📝 Summary

Summary by CodeRabbit

• Bug Fixes
  • Interrupted code-indexing scans now return the index to a standby state without starting the watcher or marking indexing complete.
  • Full scans report failures when indexing yields no results or exceeds defined error thresholds. Incremental scans can still complete when individual batches encounter errors.
  • Scan progress and indexing status are handled consistently across full and incremental scans.

Walkthrough

The indexing scan logic moved from CodeIndexOrchestrator into a new CodeIndexScanExecutor. The executor handles shared progress, cancellation, result validation, and distinct full and incremental scan policies. The orchestrator delegates both scan modes and retains cancellation cleanup and completion flow. Tests cover executor behavior and orchestrator ordering.

Changes

Code index scan execution

Layer / File(s)	Summary
Shared scan execution src/services/code-index/code-index-scan-executor.ts, src/services/code-index/__tests__/code-index-scan-executor.spec.ts	The executor marks indexing incomplete, forwards scan inputs and progress, collects batch errors, and handles cancellation, missing results, and propagated failures. Tests cover these behaviors.
Full and incremental scan policies src/services/code-index/code-index-scan-executor.ts, src/services/code-index/__tests__/code-index-scan-executor.spec.ts	Full scans validate indexed counts and batch errors. Incremental scans can succeed despite batch errors. Tests cover empty scans and the full-scan failure cases.
Orchestrator delegation and lifecycle src/services/code-index/orchestrator.ts, src/services/code-index/__tests__/orchestrator.spec.ts	The orchestrator constructs the executor and delegates both scan modes. Tests cover successful event ordering and cancellation cleanup, including a retried cache flush.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Refactor

Merge Risk: ⚪ Minimal · up to d2c05

No identified scan-behavior issue prevents merging after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to d2c05

The reviewed scan paths preserve the existing indexing and cancellation controls, and no new security exposure was established. The new executor can be called independently, so its intended internal use remains an important boundary.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The demonstrated production effect is confined to the orchestrator-selected workspace scan and its index state. Independent callers could supply another path and scanner, but none was established in the inspected runtime source.

Trust Boundaries and Controls

• observed — The orchestrator checks workspace availability, configuration, and processing state before creating the abort controller. It handles a cancelled return or rejection and marks indexing complete only after watcher startup.

Resilience and Maintainability Implications

• observed — A scanner return after abort produces a cancellation result; scanner rejection remains uncaught by the executor. The orchestrator retains cache and watcher cleanup and resets run ownership in its finally block.

🚥 Pre-merge checks | ✅ 8

✅ Passed checks (8 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR implements the scan-execution portion of #1819. CodeIndexScanExecutor extracts shared progress aggregation, cancellation handling, result checks, and full-scan policy. The orchestrator retain…
Out of Scope Changes check	✅ Passed	The changed source files and tests support #1819's scan-execution extraction. The PR adds no settings, providers, index-format changes, or unrelated product behavior. The orchestrator changes only del…
Regression Evidence	✅ Passed	PASS. The extraction has focused executor tests for both scan modes, progress and signal wiring, cancellation precedence, missing results, scanner and marker failures, full-scan threshold and preceden…
Security Boundaries	✅ Passed	No changed path meets the security failure conditions. The new executor passes the manager-provided workspace path to the existing scanner and preserves its existing .gitignore/.rooignore and supporte…
Persistence Integrity	✅ Passed	No persistence-integrity failure was introduced. The extracted scan path still awaits markIndexingIncomplete(), and the orchestrator still awaits markIndexingComplete(), cache flushes, cache clear…
Lifecycle Resource Cleanup	✅ Passed	No changed lifecycle path introduces a leak or duplicate work. The new executor only relocates markIndexingIncomplete, scanDirectory, progress aggregation, and validation; it owns no listener, wat…
Title check	✅ Passed	The title clearly identifies the primary change: extracting scan execution from the code-index orchestrator while preserving behavior.
Description check	✅ Passed	The description clearly explains the implementation, behavior-preservation goals, excluded work, linked issue, and validation results. It does not use the template's exact Test Procedure or Pre-Submis…

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Review status

Thanks for contributing. This comment tracks the review sequence and the next action.

Current step: Awaiting fresh human maintainer or CODEOWNER approval.

Automated review is complete for the latest commit but does not replace human approval.

Review-state labels are managed by this workflow; do not edit them manually.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!