fix(github-workflow): full release history for bucketing + milestone semver guard (#12188) (#12192)

Issue/PR bucketing resolved closedAt-to-release over a syncStartDate-floored sortedReleases, so every pre-floor closed item collapsed into the oldest in-window release (a v8.1.0 catch-all of 4133/7263 archived issues). Now fetch the full release history into the bucketing reference while keeping release-notes floored in syncNotes (no extra on-disk notes or SSR routes); maxReleases raised above the total release count.

Also guard the milestone-to-version branch with semver.valid so descriptive milestones no longer become garbage version folders; they fall through to closedAt-to-release.

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>

Author: neo-opus-ada

ai/mcp/server/github-workflow/config.template.mjs

@@ -197,10 +197,13 @@ class Config extends BaseConfig {
                  */
                 maxIssues: leaf(20000),
                 /**
-                 * The maximum number of releases to fetch from the GitHub API.
+                 * Safety cap on releases fetched from the GitHub API. Must exceed the repo's total
+                 * release count: the closed-item bucketing reference (`ReleaseNotesSyncer.sortedReleases`)
+                 * spans the full history, so a cap below the total would drop the oldest releases and
+                 * mis-bucket pre-cap closed items.
                  * @type {number}
                  */
-                maxReleases: leaf(1000),
+                maxReleases: leaf(2000),
                 /**
                  * The number of releases to fetch per page in GraphQL queries.
                  * @type {number}

ai/services/github-workflow/sync/IssueSyncer.mjs

@@ -353,7 +353,10 @@ class IssueSyncer extends Base {
         for (const issue of combined.values()) {
             let version = null;
             if (issue.state === 'CLOSED') {
-                if (issue.milestone?.title) {
+                // Treat a milestone as a version bucket ONLY when its title is valid semver. A
+                // descriptive milestone (e.g. "neo.d.ts - Typescript definitions") must not become
+                // a version folder; non-semver milestones fall through to closedAt→release resolution.
+                if (issue.milestone?.title && semver.valid(semver.clean(issue.milestone.title))) {
                     version = issue.milestone.title.startsWith(issueSyncConfig.versionDirectoryPrefix)
                         ? issue.milestone.title
                         : issueSyncConfig.versionDirectoryPrefix + issue.milestone.title;

ai/services/github-workflow/sync/PullRequestSyncer.mjs

@@ -5,6 +5,7 @@ import fs                         from 'fs/promises';
 import logger                     from '../../../mcp/server/github-workflow/logger.mjs';
 import matter                     from 'gray-matter';
 import path                       from 'path';
+import semver                     from 'semver';
 import GraphqlService             from '../GraphqlService.mjs';
 import ReleaseNotesSyncer         from './ReleaseNotesSyncer.mjs';
 import {FETCH_PULL_REQUESTS_FOR_SYNC} from '../queries/pullRequestQueries.mjs';
@@ -108,7 +109,9 @@ class PullRequestSyncer extends Base {
 
         for (const pr of combined.values()) {
             let version = null;
-            if (pr.milestone?.title) {
+            // Treat a milestone as a version bucket ONLY when its title is valid semver — a
+            // descriptive milestone must not become a version folder (mirrors IssueSyncer).
+            if (pr.milestone?.title && semver.valid(semver.clean(pr.milestone.title))) {
                 version = pr.milestone.title.startsWith(issueSyncConfig.versionDirectoryPrefix)
                     ? pr.milestone.title
                     : issueSyncConfig.versionDirectoryPrefix + pr.milestone.title;

ai/services/github-workflow/sync/ReleaseNotesSyncer.mjs

@@ -59,14 +59,16 @@ class ReleaseNotesSyncer extends Base {
     }
 
     /**
-     * Fetches releases from GitHub using an optimized two-phase approach.
+     * Fetches the full release history from GitHub using a two-phase approach.
      *
-     * This optimization is necessary because the GitHub GraphQL `releases` endpoint does not
+     * The two phases are necessary because the GitHub GraphQL `releases` endpoint does not
      * support a `since` parameter, making simple delta-based fetching impossible.
      *
-     * First, it performs a quick check to see if the latest release is already cached.
-     * If not, it performs a full, paginated fetch with an early-exit optimization that
-     * stops querying when it reaches releases older than the `syncStartDate`.
+     * First, a quick check sees whether the latest release is already cached (fast-path no-op).
+     * If not, it performs a full paginated fetch of the COMPLETE release history (bounded only by
+     * the `maxReleases` safety cap). The full set populates `sortedReleases`, the bucketing
+     * reference for closed Issues/PRs/Discussions; release-NOTES are floored to `syncStartDate`
+     * downstream in `syncNotes`.
      *
      * @param {object} metadata The sync metadata containing the cached releases.
      * @returns {Promise<void>}
@@ -108,14 +110,16 @@ class ReleaseNotesSyncer extends Base {
             }
         }
 
-        // Full paginated fetch with early exit.
-        logger.info('Fetching releases from GitHub via GraphQL...');
+        // Full paginated fetch of the COMPLETE release history. The bucketing reference
+        // (`sortedReleases`, consumed by Issue/PR/Discussion closedAt→release resolution) must span
+        // every release; otherwise closed items predating the oldest fetched release all collapse
+        // into it (a catch-all bucket). Release-NOTES are floored separately in syncNotes.
+        logger.info('Fetching the full release history from GitHub via GraphQL...');
 
         let allReleases   = [];
         let hasNextPage   = true;
         let cursor        = null;
         const maxReleases = issueSyncConfig.maxReleases;
-        const startDate   = new Date(issueSyncConfig.syncStartDate);
 
         while (hasNextPage && allReleases.length < maxReleases) {
             const data = await GraphqlService.query(FETCH_RELEASES, {
@@ -132,34 +136,29 @@ class ReleaseNotesSyncer extends Base {
                 break;
             }
 
-            // Check if oldest release in this batch is before our cutoff
-            const oldestInBatch = releases.nodes[releases.nodes.length - 1];
-            const oldestDate    = new Date(oldestInBatch.publishedAt);
-
-            // Add all releases from the batch for now; we will filter after the loop
             allReleases.push(...releases.nodes);
 
-            logger.debug(`Fetched ${releases.nodes.length} releases (total raw: ${allReleases.length})`);
-
-            // Early exit if oldest release in batch is before our cutoff
-            if (oldestDate < startDate) {
-                logger.info(`Reached releases published before ${issueSyncConfig.syncStartDate}, stopping pagination.`);
-                break;
-            }
+            logger.debug(`Fetched ${releases.nodes.length} releases (total: ${allReleases.length})`);
 
             hasNextPage = releases.pageInfo.hasNextPage;
             cursor      = releases.pageInfo.endCursor;
         }
 
-        // Now, filter and sort the collected releases
-        const filteredAndSortedReleases = allReleases
-            .filter(release => new Date(release.publishedAt) >= startDate)
+        // No silent truncation: warn if the safety cap was hit before history was exhausted.
+        if (hasNextPage && allReleases.length >= maxReleases) {
+            logger.warn(`⚠️ Hit maxReleases cap (${maxReleases}) before exhausting the release history; the oldest releases are missing from the bucketing reference. Raise issueSyncConfig.maxReleases.`);
+        }
+
+        // Sort the COMPLETE set ascending. Both the release map and the bucketing reference span the
+        // full history; release-NOTES are floored by syncStartDate in syncNotes, so this wide set
+        // never reaches disk as extra notes or SSR routes.
+        const allSorted = allReleases
             .sort((a, b) => new Date(a.publishedAt) - new Date(b.publishedAt));
 
         this.releases       = {};
         this.sortedReleases = [];
 
-        filteredAndSortedReleases.forEach(release => {
+        allSorted.forEach(release => {
             this.releases[release.tagName] = release;
             this.sortedReleases.push({
                 tagName    : release.tagName,
@@ -168,9 +167,9 @@ class ReleaseNotesSyncer extends Base {
         });
 
         if (Object.keys(this.releases).length === 0) {
-            logger.warn(`⚠️ No releases found since syncStartDate (${issueSyncConfig.syncStartDate}). Archiving may fall back to default.`);
+            logger.warn('⚠️ No releases found. Archiving will fall back to active/Backlog.');
         } else {
-            logger.info(`Found and cached ${Object.keys(this.releases).length} releases since ${issueSyncConfig.syncStartDate}.`);
+            logger.info(`Found and cached ${Object.keys(this.releases).length} releases (full history).`);
         }
     }
 
@@ -205,10 +204,18 @@ class ReleaseNotesSyncer extends Base {
         };
 
         const cachedReleases = metadata.releases || {};
+        const startDate      = new Date(issueSyncConfig.syncStartDate);
+
+        // Release-notes content is floored to syncStartDate even though the bucketing reference
+        // (`sortedReleases`) now spans the full history: we only write notes for in-window releases,
+        // keeping the on-disk notes set and its chunk layout stable. Index within the floored set so
+        // chunk numbers match the notes actually written.
+        const notesReleases = this.sortedReleases.filter(r => new Date(r.publishedAt) >= startDate);
 
         for (const release of Object.values(this.releases)) {
+            if (new Date(release.publishedAt) < startDate) continue;
             try {
-                const itemIndex = this.sortedReleases.findIndex(r => r.tagName === release.tagName);
+                const itemIndex = notesReleases.findIndex(r => r.tagName === release.tagName);
                 const chunkNumber = chunkNumberFor(itemIndex);
 
                 const filename = release.tagName.startsWith(issueSyncConfig.releaseFilenamePrefix)

test/playwright/unit/ai/services/github-workflow/IssueSyncer.spec.mjs

@@ -38,6 +38,7 @@ import path            from 'path';
  */
 test.describe('Neo.ai.services.github-workflow.sync.IssueSyncer', () => {
     let IssueSyncer;
+    let ReleaseNotesSyncer;
     let GraphqlService;
     let issueSyncConfig;
     let aiConfig;
@@ -66,6 +67,7 @@ test.describe('Neo.ai.services.github-workflow.sync.IssueSyncer', () => {
 
         GraphqlService = (await import('../../../../../../ai/services/github-workflow/GraphqlService.mjs')).default;
         IssueSyncer    = (await import('../../../../../../ai/services/github-workflow/sync/IssueSyncer.mjs')).default;
+        ReleaseNotesSyncer = (await import('../../../../../../ai/services/github-workflow/sync/ReleaseNotesSyncer.mjs')).default;
         logger         = (await import('../../../../../../ai/mcp/server/github-workflow/logger.mjs')).default;
 
         originalQuery = GraphqlService.query.bind(GraphqlService);
@@ -257,6 +259,49 @@ test.describe('Neo.ai.services.github-workflow.sync.IssueSyncer', () => {
         expect(targetPath).not.toContain('unversioned');
     });
 
+    test('non-semver milestone is not a version bucket — falls through to closedAt→release (#12184)', async () => {
+        // A descriptive (non-semver) milestone must NOT become a `v<title>` archive folder. Empirical:
+        // #3286/#3287 carried milestones like "neo.d.ts - Typescript definitions ..." and were archived
+        // as garbage version folders. With the semver guard, such a closed issue falls through to the
+        // closedAt→release resolution and buckets into the real release that shipped after it closed.
+        const mockIssue = buildMockIssue({
+            number       : 3286,
+            title        : 'Mock non-semver-milestone issue',
+            timelineFirst: [],
+            hasNextPage  : false,
+            endCursor    : null
+        });
+        mockIssue.state     = 'CLOSED';
+        mockIssue.closedAt  = '2024-09-15T00:00:00Z';
+        mockIssue.milestone = {title: 'neo.d.ts - Typescript definitions for all neo framework classes'};
+
+        // A real release published AFTER the issue closed → the closedAt→release fallback resolves here.
+        const originalSorted = ReleaseNotesSyncer.sortedReleases;
+        ReleaseNotesSyncer.sortedReleases = [{tagName: 'v9.0.0', publishedAt: '2024-10-01T00:00:00Z'}];
+
+        GraphqlService.query = async (query) => {
+            if (query.includes('FetchSingleIssue')) {
+                return {repository: {issue: structuredClone(mockIssue)}};
+            }
+            throw new Error(`Unexpected GraphQL query in test: ${query.slice(0, 80)}`);
+        };
+
+        const metadata = {issues: {}};
+
+        try {
+            const stats = await IssueSyncer.refetchIssuesByNumber([mockIssue.number], metadata);
+            expect(stats.refetched.count).toBe(1);
+            expect(stats.errors).toHaveLength(0);
+
+            const bucketPath = metadata.issues[mockIssue.number].path;
+            // Bucketed into the real release, NOT a title-derived garbage folder.
+            expect(bucketPath).toContain(path.join('archive', 'issues', 'v9.0.0'));
+            expect(bucketPath).not.toContain('neo.d.ts');
+        } finally {
+            ReleaseNotesSyncer.sortedReleases = originalSorted;
+        }
+    });
+
     test('pullFromGitHub enforces sealed-chunk archive semantics', async () => {
         const mockIssue = buildMockIssue({
             number       : 42044,

test/playwright/unit/ai/services/github-workflow/PullRequestSyncer.spec.mjs

@@ -116,6 +116,39 @@ test.describe('Neo.ai.services.github-workflow.sync.PullRequestSyncer', () => {
         // `archiveVersion` is fully retired (#11364) — it is no longer written to metadata.
         expect(metadata.pulls[prNumber].archiveVersion).toBeUndefined();
     });
+
+    test('non-semver milestone is not a version bucket — PR falls through to closedAt→release (#12184)', async () => {
+        const prNumber = 3287;
+
+        // A descriptive (non-semver) milestone must NOT become a `v<title>` archive folder (mirror of
+        // the IssueSyncer guard). The merged PR falls through to the closedAt→release resolution and
+        // buckets into the real release that shipped after it merged.
+        const pr = buildPullRequest(prNumber);
+        pr.milestone = {title: 'Neo-Material Component Library v0.1'};
+        pr.mergedAt  = '2024-09-15T00:00:00Z';
+        pr.closedAt  = '2024-09-15T00:00:00Z';
+
+        // A real release published AFTER the PR merged → the closedAt→release fallback resolves here.
+        ReleaseNotesSyncer.sortedReleases = [{tagName: 'v9.0.0', publishedAt: '2024-10-01T00:00:00Z'}];
+
+        GraphqlService.query = async () => ({
+            repository: {
+                pullRequests: {
+                    nodes   : [pr],
+                    pageInfo: {hasNextPage: false, endCursor: null}
+                }
+            }
+        });
+
+        const stats       = await PullRequestSyncer.syncPullRequests({pulls: {}});
+        const releasePath = path.join(aiConfig.issueSync.contentRoot, 'archive', 'pulls', 'v9.0.0', 'chunk-1', `pr-${prNumber}.md`);
+        const garbagePath = path.join(aiConfig.issueSync.contentRoot, 'archive', 'pulls', 'vNeo-Material Component Library v0.1', 'chunk-1', `pr-${prNumber}.md`);
+
+        expect(stats.synced).toEqual([prNumber]);
+        // Bucketed into the real release, NOT a title-derived garbage folder.
+        await expect(fs.pathExists(releasePath)).resolves.toBe(true);
+        await expect(fs.pathExists(garbagePath)).resolves.toBe(false);
+    });
 });
 
 function buildPullRequest(number) {