CLI-715 better support for git worktrees during integration

[sophio-japharidze-sonarsource]

---

Summary by Gitar

• Git Worktree Support:
  • Created lib/project-workspace/git-worktree.ts to canonicalize paths and resolve main working tree roots.
  • Updated analyze agentic to check both current and main working tree paths for project metadata.
• State Persistence:
  • Modified integrate commands to persist repoRoot (the main working tree) in state attributes, decoupling it from the physical targetRoot.
  • Updated sonar context to match current paths against either repoRoot or targetRoot, ensuring state persists across linked worktree creation.
• Testing:
  • Added integration tests in context-augmentation.test.ts and analyze-sqaa.test.ts to verify cross-worktree state resolution.
• Documentation:
  • Updated CLAUDE.md to detail worktree-aware resolution logic for SQAA and Context Augmentation.

_{This will update automatically on new commits.}

[netlify]

✅ Deploy Preview for sonarqube-cli ready!

Name	Link
🔨 Latest commit	8d11497
🔍 Latest deploy log	https://app.netlify.com/projects/sonarqube-cli/deploys/6a4cdf678bdcdd000831f41e
😎 Deploy Preview	https://deploy-preview-547--sonarqube-cli.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[hashicorp-vault-sonar-prod]

CLI-715

[gitar-bot]

💡 Quality: workspaceDir doc says "current working tree" but value is main tree

The workspaceDir field's doc comment in context-augmentation-env.ts describes it as "The current working tree's root". However, the value actually assigned (in resolveRecordedContextAugmentationConfig, context/index.ts:156) is getOptionalStringAttr(match.attrs, 'repoRoot') ?? match.targetRoot — i.e. the recorded main working tree / integrated folder, deliberately NOT the current working tree. The context/index.ts comment correctly explains this ('the stable main-working-tree key ... correct from any subfolder or linked worktree'). This is the whole point of the change: CAG resolves the same workspace regardless of which linked worktree it is invoked from. The interface comment contradicts that intent and could mislead a future reader into thinking the current worktree is passed. Suggest aligning the comment with the actual semantics (the repository's main working tree / recorded integrated folder).

Correct the comment to describe the main working tree, matching the value actually passed.:

/**
 * The repository's main working tree (the recorded integrated folder), passed
 * to CAG so it can locate (or lazily create) the per-workspace daemon folder
 * consistently from any git worktree. Set only when the repository's main
 * working tree has a recorded integration.
 */
workspaceDir?: string;

• Apply fix

_{Check the box to apply the fix or reply for a change | Was this helpful? React with 👍 / 👎}

[gitar-bot]

Code Review 👍 Approved with suggestions 1 resolved / 2 findings

Improves Git worktree support by decoupling repo root from physical target paths and ensuring state consistency across branches. Please update the workspaceDir documentation to clarify that it references the main working tree rather than the current one.

💡 Quality: workspaceDir doc says "current working tree" but value is main tree

📄 src/cli/commands/_common/context-augmentation-env.ts:29-34 📄 src/cli/commands/context/index.ts:151-156

The workspaceDir field's doc comment in context-augmentation-env.ts describes it as "The current working tree's root". However, the value actually assigned (in resolveRecordedContextAugmentationConfig, context/index.ts:156) is getOptionalStringAttr(match.attrs, 'repoRoot') ?? match.targetRoot — i.e. the recorded main working tree / integrated folder, deliberately NOT the current working tree. The context/index.ts comment correctly explains this ('the stable main-working-tree key ... correct from any subfolder or linked worktree'). This is the whole point of the change: CAG resolves the same workspace regardless of which linked worktree it is invoked from. The interface comment contradicts that intent and could mislead a future reader into thinking the current worktree is passed. Suggest aligning the comment with the actual semantics (the repository's main working tree / recorded integrated folder).

Correct the comment to describe the main working tree, matching the value actually passed.

/**
 * The repository's main working tree (the recorded integrated folder), passed
 * to CAG so it can locate (or lazily create) the per-workspace daemon folder
 * consistently from any git worktree. Set only when the repository's main
 * working tree has a recorded integration.
 */
workspaceDir?: string;

✅ 1 resolved

✅ Quality: Test comment misstates production canonicalization behavior

📄 tests/integration/specs/integrate/context-augmentation.test.ts:44-55 📄 src/lib/project-workspace/git-worktree.ts:37-43
The new canonical() test helper comment (tests/integration/specs/integrate/context-augmentation.test.ts:44-46) states it mirrors "the production canonicalization (realpathSync.native + lowercase on Windows)". However, production canonicalize() in src/lib/project-workspace/git-worktree.ts:37-43 only calls realpathSync.native(path) and does NOT lowercase. The tests stay internally consistent because both sides of each assertion pass through the same helper, but the comment could mislead a future reader into thinking production lowercases paths (it relies on realpathSync.native returning canonical drive-letter casing instead). Suggest correcting the comment to reflect that the lowercasing is a test-only normalization that is at least as tolerant as production.

🤖 Prompt for agents

Code Review: Improves Git worktree support by decoupling repo root from physical target paths and ensuring state consistency across branches. Please update the `workspaceDir` documentation to clarify that it references the main working tree rather than the current one.

1. 💡 Quality: workspaceDir doc says "current working tree" but value is main tree
   Files: src/cli/commands/_common/context-augmentation-env.ts:29-34, src/cli/commands/context/index.ts:151-156

   The `workspaceDir` field's doc comment in `context-augmentation-env.ts` describes it as "The current working tree's root". However, the value actually assigned (in `resolveRecordedContextAugmentationConfig`, `context/index.ts:156`) is `getOptionalStringAttr(match.attrs, 'repoRoot') ?? match.targetRoot` — i.e. the recorded *main* working tree / integrated folder, deliberately NOT the current working tree. The context/index.ts comment correctly explains this ('the stable main-working-tree key ... correct from any subfolder or linked worktree'). This is the whole point of the change: CAG resolves the same workspace regardless of which linked worktree it is invoked from. The interface comment contradicts that intent and could mislead a future reader into thinking the current worktree is passed. Suggest aligning the comment with the actual semantics (the repository's main working tree / recorded integrated folder).

   Fix (Correct the comment to describe the main working tree, matching the value actually passed.):
   /**
    * The repository's main working tree (the recorded integrated folder), passed
    * to CAG so it can locate (or lazily create) the per-workspace daemon folder
    * consistently from any git worktree. Set only when the repository's main
    * working tree has a recorded integration.
    */
   workspaceDir?: string;

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change the behavior for this request:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Gitar}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues
0 New dependency risks

Measures
0 Security Hotspots
91.8% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud