@link-assistant/hive-mind 0.50.11 → 0.51.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @link-assistant/hive-mind
 
+## 0.51.0
+
+### Minor Changes
+
+- 36f23fb: Add fork parent validation to prevent nested fork hierarchy issues (#967)
+
+  This release adds early validation of fork parent relationships to prevent issues where a fork was created from an intermediate fork (fork of a fork) instead of directly from the intended upstream repository.
+
+  **Problem solved:**
+  When a user's fork was created from an intermediate fork (e.g., `user/repo` forked from `someone-else/repo` which was itself forked from `upstream/repo`), any pull requests created would include all commits that exist in the intermediate fork but not in the upstream. This could result in PRs with hundreds or thousands of unexpected commits.
+
+  **Case study (Issue #967):**
+  A fork `konard/zamtmn-zcad` was created from `veb86/zcadvelecAI` (intermediate fork with 1,678 extra commits) instead of `zamtmn/zcad` (the upstream). This resulted in a PR with 1,681 commits instead of the expected 3 commits.
+
+  **Changes:**
+  - **New function `validateForkParent()`**: Validates that a fork's parent matches the expected upstream repository before using it. Checks both the immediate parent and ultimate source (root) of the fork hierarchy.
+  - **Early validation**: Fork parent is now validated immediately after an existing fork is found, BEFORE syncing or creating branches. This prevents wasted work and provides clear error messages early.
+  - **Detailed error messages**: When a fork parent mismatch is detected, users receive comprehensive information including:
+    - The actual fork hierarchy (parent and source repositories)
+    - Why this is a problem (unexpected commits in PRs)
+    - Three concrete fix options:
+      1. Delete the problematic fork and create a fresh one
+      2. Use `--prefix-fork-name-with-owner-name` to create a new fork with a different name
+      3. Work directly on the repository with `--no-fork` if you have write access
+  - **Unit tests**: Added comprehensive test suite (`tests/test-fork-parent-validation.mjs`) with 10 tests covering the validation logic, error handling, and documentation.
+
+  **Technical details:**
+  - Uses GitHub API to fetch fork relationship: `gh api repos/{fork} --jq '{fork: .fork, parent: .parent.full_name, source: .source.full_name}'`
+  - Validates in two code paths: when finding existing forks (strict error) and when using forkOwner from PR mode (warning only)
+  - Reports validation errors to Sentry for monitoring
+
 ## 0.50.11
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "0.50.11",
+  "version": "0.51.0",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/solve.repository.lib.mjs

@@ -97,6 +97,100 @@ export const checkExistingForkOfRoot = async rootRepo => {
   }
 };
 
+/**
+ * Validate that a fork's parent matches the expected upstream repository.
+ * This prevents issues where a fork was created from an intermediate fork (fork of a fork)
+ * instead of directly from the intended upstream repository.
+ *
+ * @param {string} forkRepo - The fork repository to validate (e.g., "user/repo")
+ * @param {string} expectedUpstream - The expected upstream repository (e.g., "owner/repo")
+ * @returns {Promise<{isValid: boolean, isFork: boolean, parent: string|null, source: string|null, error: string|null}>}
+ */
+export const validateForkParent = async (forkRepo, expectedUpstream) => {
+  try {
+    const forkInfoResult = await $`gh api repos/${forkRepo} --jq '{fork: .fork, parent: .parent.full_name, source: .source.full_name}'`;
+
+    if (forkInfoResult.code !== 0) {
+      return {
+        isValid: false,
+        isFork: false,
+        parent: null,
+        source: null,
+        error: `Failed to get fork info for ${forkRepo}`,
+      };
+    }
+
+    const forkInfo = JSON.parse(forkInfoResult.stdout.toString().trim());
+    const isFork = forkInfo.fork === true;
+    const parent = forkInfo.parent || null;
+    const source = forkInfo.source || null;
+
+    // If not a fork at all, it's invalid for our purposes
+    if (!isFork) {
+      return {
+        isValid: false,
+        isFork: false,
+        parent: null,
+        source: null,
+        error: `Repository ${forkRepo} is not a GitHub fork`,
+      };
+    }
+
+    // The fork's PARENT (immediate upstream) should match expectedUpstream
+    // The SOURCE (ultimate root) is also acceptable as it indicates the fork
+    // is part of the correct hierarchy, just at a different level
+    const parentMatches = parent === expectedUpstream;
+    const sourceMatches = source === expectedUpstream;
+
+    // Ideal case: parent matches directly (fork was made from expected upstream)
+    if (parentMatches) {
+      return {
+        isValid: true,
+        isFork: true,
+        parent,
+        source,
+        error: null,
+      };
+    }
+
+    // Special case: source matches but parent doesn't
+    // This means the fork was made from an intermediate fork
+    // For issue #967, this is the problematic case we want to catch
+    if (sourceMatches && !parentMatches) {
+      return {
+        isValid: false,
+        isFork: true,
+        parent,
+        source,
+        error: `Fork ${forkRepo} was created from ${parent} (intermediate fork), not directly from ${expectedUpstream}. ` + `This can cause pull requests to include unexpected commits from the intermediate fork.`,
+      };
+    }
+
+    // Neither parent nor source matches - completely different repository tree
+    return {
+      isValid: false,
+      isFork: true,
+      parent,
+      source,
+      error: `Fork ${forkRepo} is from a different repository tree (parent: ${parent}, source: ${source}) and cannot be used with ${expectedUpstream}`,
+    };
+  } catch (error) {
+    reportError(error, {
+      context: 'validate_fork_parent',
+      forkRepo,
+      expectedUpstream,
+      operation: 'check_fork_hierarchy',
+    });
+    return {
+      isValid: false,
+      isFork: false,
+      parent: null,
+      source: null,
+      error: `Error validating fork parent: ${error.message}`,
+    };
+  }
+};
+
 // Create or find temporary directory for cloning the repository
 export const setupTempDirectory = async argv => {
   let tempDir;
@@ -315,8 +409,61 @@ export const setupRepository = async (argv, owner, repo, forkOwner = null, issue
     }
 
     if (existingForkName) {
-      // Fork exists
+      // Fork exists - validate that its parent matches the expected upstream
       await log(`${formatAligned('✅', 'Fork exists:', existingForkName)}`);
+      await log(`${formatAligned('🔍', 'Validating fork parent...', '')}`);
+
+      const forkValidation = await validateForkParent(existingForkName, `${owner}/${repo}`);
+
+      if (!forkValidation.isValid) {
+        // Fork parent mismatch detected - this prevents issue #967
+        await log('');
+        await log(`${formatAligned('❌', 'FORK PARENT MISMATCH DETECTED', '')}`, { level: 'error' });
+        await log('');
+        await log('  🔍 What happened:');
+        if (!forkValidation.isFork) {
+          await log(`     The repository ${existingForkName} is NOT a GitHub fork.`);
+          await log('     It may have been created by cloning and pushing instead of forking.');
+        } else {
+          await log(`     Your fork ${existingForkName} was created from an intermediate fork,`);
+          await log(`     not directly from the target repository ${owner}/${repo}.`);
+        }
+        await log('');
+        await log('  📦 Fork relationship:');
+        await log(`     • Your fork: ${existingForkName}`);
+        await log(`     • Fork parent: ${forkValidation.parent || 'N/A (not a fork)'}`);
+        await log(`     • Fork source (root): ${forkValidation.source || 'N/A'}`);
+        await log(`     • Expected parent: ${owner}/${repo}`);
+        await log('');
+        await log('  ⚠️  Why this is a problem:');
+        await log('     When a fork is created from an intermediate fork (a "fork of a fork"),');
+        await log('     any commits that exist in the intermediate fork but not in the target');
+        await log('     repository will be included in your pull requests. This can result in');
+        await log('     pull requests with hundreds or thousands of unexpected commits.');
+        await log('');
+        await log('  📖 Case study: See issue #967');
+        await log('     A fork created from veb86/zcadvelecAI (which had 1,678 extra commits)');
+        await log('     instead of zamtmn/zcad resulted in a PR with 1,681 commits');
+        await log('     instead of the expected 3 commits.');
+        await log('');
+        await log('  💡 How to fix:');
+        await log('');
+        await log('     Option 1: Delete the problematic fork and create a fresh one');
+        await log(`        gh repo delete ${existingForkName}`);
+        await log(`        Then run this command again to create a proper fork of ${owner}/${repo}`);
+        await log('');
+        await log('     Option 2: Use --prefix-fork-name-with-owner-name to create a new fork');
+        await log(`        This creates a fork named ${currentUser}/${owner}-${repo} instead`);
+        await log(`        ./solve.mjs "${issueUrl || `https://github.com/${owner}/${repo}/issues/<number>`}" --prefix-fork-name-with-owner-name --fork`);
+        await log('');
+        await log('     Option 3: Work directly on the repository (if you have write access)');
+        await log(`        ./solve.mjs "${issueUrl || `https://github.com/${owner}/${repo}/issues/<number>`}" --no-fork`);
+        await log('');
+
+        await safeExit(1, 'Fork parent mismatch - fork was created from intermediate fork');
+      }
+
+      await log(`${formatAligned('✅', 'Fork parent validated:', `${forkValidation.parent}`)}`);
       repoToClone = existingForkName;
       forkedRepo = existingForkName;
       upstreamRemote = `${owner}/${repo}`;
@@ -555,6 +702,39 @@ Thank you!`;
 
     if (forkCheckResult.code === 0) {
       await log(`${formatAligned('✅', 'Fork verified:', `${actualForkName} is accessible`)}`);
+
+      // Validate fork parent before using it (prevents issue #967)
+      await log(`${formatAligned('🔍', 'Validating fork parent...', '')}`);
+      const forkValidation = await validateForkParent(actualForkName, `${owner}/${repo}`);
+
+      if (!forkValidation.isValid) {
+        // Fork parent mismatch detected
+        await log('');
+        await log(`${formatAligned('⚠️', 'FORK PARENT MISMATCH WARNING', '')}`, { level: 'warning' });
+        await log('');
+        await log('  🔍 Issue detected:');
+        if (!forkValidation.isFork) {
+          await log(`     The repository ${actualForkName} is NOT a GitHub fork.`);
+        } else {
+          await log(`     The fork ${actualForkName} was created from ${forkValidation.parent},`);
+          await log(`     not directly from the target repository ${owner}/${repo}.`);
+        }
+        await log('');
+        await log('  📦 Fork relationship:');
+        await log(`     • Fork: ${actualForkName}`);
+        await log(`     • Fork parent: ${forkValidation.parent || 'N/A'}`);
+        await log(`     • Fork source (root): ${forkValidation.source || 'N/A'}`);
+        await log(`     • Expected parent: ${owner}/${repo}`);
+        await log('');
+        await log('  ⚠️  This may cause pull requests to include unexpected commits.');
+        await log('     Consider using --fork to create your own fork instead.');
+        await log('');
+        // Note: We don't exit here since this is someone else's fork and we're just using it
+        // The user should be aware but can proceed (they didn't create this fork)
+      } else {
+        await log(`${formatAligned('✅', 'Fork parent validated:', `${forkValidation.parent}`)}`);
+      }
+
       repoToClone = actualForkName;
       forkedRepo = actualForkName;
       upstreamRemote = `${owner}/${repo}`;