ado-sync 0.1.64 → 0.1.67

package/dist/sync/engine.js

@@ -41,6 +41,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.failOnParseErrors = failOnParseErrors;
 exports.buildPushDiff = buildPushDiff;
+exports.validatePushModeOptions = validatePushModeOptions;
 exports.push = push;
 exports.pull = pull;
 exports.status = status;
@@ -313,6 +314,36 @@ async function parseLocalFiles(filePaths, config, tagsFilter) {
     }
     return { tests: results, failures };
 }
+function validatePushModeOptions(opts) {
+    const enabledModes = [
+        opts.createOnly && '--create-only',
+        opts.linkOnly && '--link-only',
+        opts.updateOnly && '--update-only',
+    ].filter(Boolean);
+    if (enabledModes.length > 1) {
+        throw new Error(`Only one push mode can be used at a time: ${enabledModes.join(', ')}`);
+    }
+}
+function filterDiscoveredFiles(filePaths, sourceFiles) {
+    if (!sourceFiles?.length)
+        return filePaths;
+    const requested = new Set(sourceFiles.map((filePath) => path.normalize(path.resolve(filePath))));
+    return filePaths.filter((filePath) => requested.has(path.normalize(filePath)));
+}
+function formatSuitePreview(pathKey) {
+    if (!pathKey)
+        return undefined;
+    return pathKey.split('/').join(' / ');
+}
+function mapRemoteTestsByTitle(testCases) {
+    const byTitle = new Map();
+    for (const testCase of testCases) {
+        const matches = byTitle.get(testCase.title) ?? [];
+        matches.push(testCase);
+        byTitle.set(testCase.title, matches);
+    }
+    return byTitle;
+}
 // ─── Multi-plan helpers ───────────────────────────────────────────────────────
 /**
  * Build an effective config for a single plan entry in testPlans[] mode.
@@ -330,6 +361,7 @@ function configForPlanEntry(base, entry) {
         testPlan: {
             id: entry.id,
             suiteId: entry.suiteId ?? base.testPlan.suiteId,
+            hierarchy: entry.hierarchy ?? base.testPlan.hierarchy,
             suiteMapping: entry.suiteMapping ?? base.testPlan.suiteMapping,
             suiteRouting: entry.suiteRouting ?? base.testPlan.suiteRouting,
         },
@@ -375,6 +407,7 @@ async function resolveTargetSuiteFromRouting(client, config, test, suiteCache) {
 }
 // ─── Push ─────────────────────────────────────────────────────────────────────
 async function push(config, configDir, opts = {}) {
+    validatePushModeOptions(opts);
     // Multi-plan: run AI summarisation across all plans first so progress totals
     // are correct, then delegate each plan's sync loop (with AI already applied).
     if (config.testPlans?.length) {
@@ -383,7 +416,7 @@ async function push(config, configDir, opts = {}) {
         const parseFailures = [];
         for (const entry of config.testPlans) {
             const entryConfig = configForPlanEntry(config, entry);
-            const files = await discoverFiles(entryConfig.local.include, entryConfig.local.exclude, configDir);
+            const files = filterDiscoveredFiles(await discoverFiles(entryConfig.local.include, entryConfig.local.exclude, configDir), opts.sourceFiles);
             const parsed = await parseLocalFiles(files, entryConfig, opts.tags);
             parseFailures.push(...parsed.failures);
             const tests = parsed.tests;
@@ -430,7 +463,7 @@ async function pushSingle(config, configDir, opts) {
     let resolvedTests = opts._preloadedTests ?? [];
     let parseFailures = [];
     if (!opts._preloadedTests) {
-        const files = await discoverFiles(config.local.include, config.local.exclude, configDir);
+        const files = filterDiscoveredFiles(await discoverFiles(config.local.include, config.local.exclude, configDir), opts.sourceFiles);
         const parsed = await parseLocalFiles(files, config, opts.tags);
         resolvedTests = parsed.tests;
         parseFailures = parsed.failures;
@@ -515,7 +548,7 @@ async function pushSingle(config, configDir, opts) {
     const titleField = config.sync?.titleField ?? 'System.Title';
     const conflictAction = config.sync?.conflictAction ?? 'overwrite';
     const disableLocal = config.sync?.disableLocalChanges ?? false;
-    const byFolder = config.testPlan.suiteMapping === 'byFolder' || config.testPlan.suiteMapping === 'byFile';
+    const byFolder = (0, test_cases_1.usesGeneratedSuiteHierarchy)(config);
     // Load local cache for conflict detection and skip optimisation
     const cache = (0, cache_1.loadCache)(configDir);
     // G: seed in-memory suite cache from persisted _suites to avoid redundant API calls
@@ -535,18 +568,24 @@ async function pushSingle(config, configDir, opts) {
     const markAutomated = config.sync?.markAutomated ?? false;
     const recoveredIds = new Set(); // "filePath:line" keys
     let preloadedRemoteTcs;
+    let remoteByTitle;
     const unlinkedWithAtName = resolvedTests.filter(t => !t.azureId && t.automatedTestName);
-    if (markAutomated && unlinkedWithAtName.length > 0) {
+    const shouldPreloadRemoteTcs = (markAutomated && unlinkedWithAtName.length > 0)
+        || (opts.linkOnly && resolvedTests.some((test) => !test.azureId));
+    if (shouldPreloadRemoteTcs) {
         try {
             preloadedRemoteTcs = await (0, test_cases_1.getTestCasesInSuite)(client, config);
-            const byAtName = new Map(preloadedRemoteTcs
-                .filter(tc => tc.automatedTestName)
-                .map(tc => [tc.automatedTestName, tc]));
-            for (const test of unlinkedWithAtName) {
-                const match = byAtName.get(test.automatedTestName);
-                if (match) {
-                    test.azureId = match.id;
-                    recoveredIds.add(`${test.filePath}:${test.line}`);
+            remoteByTitle = mapRemoteTestsByTitle(preloadedRemoteTcs);
+            if (markAutomated && unlinkedWithAtName.length > 0) {
+                const byAtName = new Map(preloadedRemoteTcs
+                    .filter(tc => tc.automatedTestName)
+                    .map(tc => [tc.automatedTestName, tc]));
+                for (const test of unlinkedWithAtName) {
+                    const match = byAtName.get(test.automatedTestName);
+                    if (match) {
+                        test.azureId = match.id;
+                        recoveredIds.add(`${test.filePath}:${test.line}`);
+                    }
                 }
             }
         }
@@ -594,7 +633,19 @@ async function pushSingle(config, configDir, opts) {
     const pushWorkers = Array.from({ length: Math.min(PUSH_CONCURRENCY, pushQueue.length) }, async () => {
         while (pushQueue.length > 0) {
             const test = pushQueue.shift();
+            const currentHierarchyKey = byFolder ? (0, test_cases_1.getGeneratedSuitePathKeyForTest)(config, test, configDir) : undefined;
+            const targetSuitePath = formatSuitePreview(currentHierarchyKey);
             if (test.azureId) {
+                if (opts.createOnly || opts.linkOnly) {
+                    reportProgress({
+                        action: 'skipped',
+                        filePath: test.filePath,
+                        title: test.title,
+                        azureId: test.azureId,
+                        detail: opts.createOnly ? 'skipped by create-only mode' : 'already linked; skipped by link-only mode',
+                    });
+                    continue;
+                }
                 try {
                     const cached = cache[test.azureId];
                     // Use pre-fetched TC from cache; fall back to live fetch on miss
@@ -602,11 +653,21 @@ async function pushSingle(config, configDir, opts) {
                         ? remoteTcCache.get(test.azureId)
                         : await (0, test_cases_1.getTestCase)(client, test.azureId, titleField);
                     if (!remote) {
+                        if (opts.updateOnly) {
+                            reportProgress({
+                                action: 'skipped',
+                                filePath: test.filePath,
+                                title: test.title,
+                                azureId: test.azureId,
+                                detail: 'remote test case missing; skipped by update-only mode',
+                            });
+                            continue;
+                        }
                         // TC was deleted from Azure — re-create it and write back the new ID.
                         let newId;
                         if (!opts.dryRun) {
                             const suiteIdOverride = byFolder
-                                ? await (0, test_cases_1.getOrCreateSuiteForFile)(client, config, test.filePath, configDir, suiteCache)
+                                ? await (0, test_cases_1.getOrCreateGeneratedSuiteForTest)(client, config, test, configDir, suiteCache)
                                 : await resolveTargetSuiteFromRouting(client, config, test, suiteCache);
                             newId = await (0, test_cases_1.createTestCase)(client, test, config, suiteIdOverride, configDir);
                             createdIds.add(newId);
@@ -616,7 +677,7 @@ async function pushSingle(config, configDir, opts) {
                             await (0, test_cases_1.addTestCaseToConditionSuites)(client, config, newId, test, conditionSuiteCache);
                             const created = await (0, test_cases_1.getTestCase)(client, newId, titleField);
                             if (created)
-                                updateCacheEntry(cache, test, created);
+                                updateCacheEntry(cache, test, created, currentHierarchyKey);
                         }
                         reportProgress({ action: 'created', filePath: test.filePath, title: test.title, azureId: newId });
                         continue;
@@ -625,23 +686,44 @@ async function pushSingle(config, configDir, opts) {
                     // Normalise local to @param@ before comparing so outlines don't report
                     // stepsChanged on every push after the first successful sync.
                     const { changedFields, diffDetail } = buildPushDiff(test, remote, config, cached);
-                    if (changedFields.length === 0) {
+                    const previousHierarchyKey = cached?.suitePathKey ?? (cached?.filePath
+                        ? (0, test_cases_1.getGeneratedSuitePathKey)(config, cached.filePath, configDir)
+                        : undefined);
+                    const suiteChanged = byFolder &&
+                        previousHierarchyKey !== undefined &&
+                        currentHierarchyKey !== undefined &&
+                        previousHierarchyKey !== currentHierarchyKey;
+                    const previousSuitePath = formatSuitePreview(previousHierarchyKey);
+                    const effectiveChangedFields = suiteChanged ? [...changedFields, 'suite'] : changedFields;
+                    const effectiveDiffDetail = suiteChanged
+                        ? [
+                            ...diffDetail,
+                            {
+                                field: 'suite',
+                                remote: previousHierarchyKey || '(plan root)',
+                                local: currentHierarchyKey || '(plan root)',
+                            },
+                        ]
+                        : diffDetail;
+                    if (effectiveChangedFields.length === 0) {
                         // Update cache entry even on skip (changedDate may differ due to other fields)
-                        updateCacheEntry(cache, test, remote);
-                        reportProgress({ action: 'skipped', filePath: test.filePath, title: test.title, azureId: test.azureId });
+                        updateCacheEntry(cache, test, remote, currentHierarchyKey);
+                        reportProgress({ action: 'skipped', filePath: test.filePath, title: test.title, azureId: test.azureId, detail: 'no changes' });
                         continue;
                     }
                     // Conflict detection: remote was changed since last push AND local also differs
-                    if (cached && remote.changedDate && remote.changedDate !== cached.changedDate) {
+                    if (changedFields.length > 0 && cached && remote.changedDate && remote.changedDate !== cached.changedDate) {
                         const relFile = path.relative(configDir, test.filePath);
                         const conflict = {
                             action: 'conflict',
                             filePath: test.filePath,
                             title: test.title,
                             azureId: test.azureId,
-                            changedFields,
-                            diffDetail,
-                            detail: `${relFile}:${test.line} — changed fields: ${changedFields.join(', ')}`,
+                            targetSuitePath,
+                            previousSuitePath,
+                            changedFields: effectiveChangedFields,
+                            diffDetail: effectiveDiffDetail,
+                            detail: `${relFile}:${test.line} — changed fields: ${effectiveChangedFields.join(', ')}`,
                         };
                         if (conflictAction === 'skip') {
                             reportProgress(conflict);
@@ -655,24 +737,39 @@ async function pushSingle(config, configDir, opts) {
                         // 'overwrite' — fall through to update
                     }
                     if (!opts.dryRun) {
-                        await (0, test_cases_1.updateTestCase)(client, test.azureId, test, config, configDir);
+                        if (changedFields.length > 0) {
+                            await (0, test_cases_1.updateTestCase)(client, test.azureId, test, config, configDir);
+                        }
                         // Ensure the TC is in the configured suite (it may not be if the suite was
                         // changed in config, or if the TC was imported with an ID but never pushed before).
                         const updateSuiteId = byFolder
-                            ? await (0, test_cases_1.getOrCreateSuiteForFile)(client, config, test.filePath, configDir, suiteCache)
+                            ? await (0, test_cases_1.getOrCreateGeneratedSuiteForTest)(client, config, test, configDir, suiteCache)
                             : await resolveTargetSuiteFromRouting(client, config, test, suiteCache) ?? config.testPlan.suiteId;
                         if (updateSuiteId) {
                             await (0, test_cases_1.addTestCaseToSuite)(client, config, test.azureId, updateSuiteId);
+                            if (suiteChanged && previousHierarchyKey) {
+                                const previousSuiteId = cached?.suitePathKey
+                                    ? await (0, test_cases_1.resolveExistingSuiteForPathKey)(client, config, previousHierarchyKey, suiteCache)
+                                    : cached?.filePath
+                                        ? await (0, test_cases_1.resolveExistingSuiteForFile)(client, config, cached.filePath, configDir, suiteCache)
+                                        : undefined;
+                                if (previousSuiteId && previousSuiteId !== updateSuiteId) {
+                                    await (0, test_cases_1.removeTestCaseFromSuite)(client, config, test.azureId, previousSuiteId);
+                                    if ((0, test_cases_1.shouldCleanupEmptyGeneratedSuites)(config)) {
+                                        await (0, test_cases_1.pruneEmptyGeneratedSuitesForPathKey)(client, config, previousHierarchyKey, suiteCache);
+                                    }
+                                }
+                            }
                         }
                         else {
                             await (0, test_cases_1.addTestCaseToRootSuite)(client, config, test.azureId);
                         }
                         await (0, test_cases_1.addTestCaseToConditionSuites)(client, config, test.azureId, test, conditionSuiteCache);
-                        const updated = await (0, test_cases_1.getTestCase)(client, test.azureId, titleField);
+                        const updated = changedFields.length > 0 ? await (0, test_cases_1.getTestCase)(client, test.azureId, titleField) : remote;
                         if (updated)
-                            updateCacheEntry(cache, test, updated);
+                            updateCacheEntry(cache, test, updated, currentHierarchyKey);
                     }
-                    reportProgress({ action: 'updated', filePath: test.filePath, title: test.title, azureId: test.azureId, changedFields, diffDetail });
+                    reportProgress({ action: 'updated', filePath: test.filePath, title: test.title, azureId: test.azureId, targetSuitePath, previousSuitePath, changedFields: effectiveChangedFields, diffDetail: effectiveDiffDetail });
                 }
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
@@ -680,11 +777,51 @@ async function pushSingle(config, configDir, opts) {
                 }
             }
             else {
+                if (opts.updateOnly) {
+                    reportProgress({
+                        action: 'skipped',
+                        filePath: test.filePath,
+                        title: test.title,
+                        detail: 'unlinked local spec; skipped by update-only mode',
+                    });
+                    continue;
+                }
+                if (opts.linkOnly) {
+                    try {
+                        const canonicalTitle = (0, test_cases_1.buildAzureSyncContent)(test, config.sync?.format).title;
+                        const titleMatches = remoteByTitle?.get(canonicalTitle) ?? [];
+                        if (titleMatches.length !== 1) {
+                            const detail = titleMatches.length === 0
+                                ? 'no unique title match found in current remote scope'
+                                : `multiple title matches found in current remote scope (${titleMatches.length})`;
+                            reportProgress({ action: 'skipped', filePath: test.filePath, title: test.title, detail });
+                            continue;
+                        }
+                        const matched = titleMatches[0];
+                        test.azureId = matched.id;
+                        recoveredIds.add(`${test.filePath}:${test.line}`);
+                        if (!opts.dryRun && !disableLocal) {
+                            pendingWritebacks.push({ test, newId: matched.id });
+                        }
+                        const detail = opts.dryRun
+                            ? 'would link to existing test case by exact title match'
+                            : disableLocal
+                                ? 'matched existing test case by exact title match (local writeback skipped)'
+                                : 'linked to existing test case by exact title match';
+                        reportProgress({ action: 'linked', filePath: test.filePath, title: test.title, azureId: matched.id, detail });
+                        continue;
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        reportProgress({ action: 'error', filePath: test.filePath, title: test.title, detail: msg });
+                        continue;
+                    }
+                }
                 try {
                     let newId;
                     if (!opts.dryRun) {
                         const suiteIdOverride = byFolder
-                            ? await (0, test_cases_1.getOrCreateSuiteForFile)(client, config, test.filePath, configDir, suiteCache)
+                            ? await (0, test_cases_1.getOrCreateGeneratedSuiteForTest)(client, config, test, configDir, suiteCache)
                             : await resolveTargetSuiteFromRouting(client, config, test, suiteCache);
                         newId = await (0, test_cases_1.createTestCase)(client, test, config, suiteIdOverride, configDir);
                         createdIds.add(newId);
@@ -695,9 +832,9 @@ async function pushSingle(config, configDir, opts) {
                         // Fetch back to get changedDate for cache
                         const created = await (0, test_cases_1.getTestCase)(client, newId, titleField);
                         if (created)
-                            updateCacheEntry(cache, test, created);
+                            updateCacheEntry(cache, test, created, currentHierarchyKey);
                     }
-                    reportProgress({ action: 'created', filePath: test.filePath, title: test.title, azureId: newId });
+                    reportProgress({ action: 'created', filePath: test.filePath, title: test.title, azureId: newId, targetSuitePath });
                 }
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
@@ -754,17 +891,17 @@ async function pushSingle(config, configDir, opts) {
         }
     }
     // Removed TC detection is only safe on full-scope runs.
-    // Tag-filtered or condition-filtered pushes intentionally operate on a subset.
-    const shouldDetectRemoved = !opts.tags && !config.local.condition;
+    // Tag-filtered, source-file-filtered, create-only, or condition-filtered pushes intentionally operate on a subset.
+    const shouldDetectRemoved = !opts.tags && !opts.sourceFiles?.length && !opts.createOnly && !opts.linkOnly && !opts.updateOnly && !config.local.condition;
+    const localIds = new Set([
+        ...resolvedTests.map((t) => t.azureId).filter(Boolean),
+        ...createdIds,
+    ]);
     if (shouldDetectRemoved) {
         try {
             // Reuse the pre-loaded remote TCs if we already fetched them for automatedTestName
             // matching, otherwise fetch now. This avoids a redundant round-trip.
             const remoteTcs = preloadedRemoteTcs ?? await (0, test_cases_1.getTestCasesInSuite)(client, config);
-            const localIds = new Set([
-                ...resolvedTests.map((t) => t.azureId).filter(Boolean),
-                ...createdIds,
-            ]);
             for (const remote of remoteTcs) {
                 if (!localIds.has(remote.id)) {
                     if (!opts.dryRun) {
@@ -782,6 +919,22 @@ async function pushSingle(config, configDir, opts) {
         }
         catch { /* best-effort: don't fail the whole push */ }
     }
+    if (!opts.dryRun && (0, test_cases_1.shouldCleanupEmptyGeneratedSuites)(config) && shouldDetectRemoved) {
+        const staleHierarchyKeys = [...new Set(Object.entries(cache)
+                .filter(([cacheKey]) => cacheKey !== '_suites')
+                .map(([cacheKey, entry]) => ({ azureId: Number(cacheKey), entry }))
+                .filter(({ azureId, entry }) => Number.isFinite(azureId) && !localIds.has(azureId) && !!entry)
+                .map(({ entry }) => entry.suitePathKey ?? (0, test_cases_1.getGeneratedSuitePathKey)(config, entry.filePath, configDir))
+                .filter((pathKey) => !!pathKey))];
+        for (const staleHierarchyKey of staleHierarchyKeys) {
+            try {
+                await (0, test_cases_1.pruneEmptyGeneratedSuitesForPathKey)(client, config, staleHierarchyKey, suiteCache);
+            }
+            catch {
+                // Best-effort cleanup; do not fail the push when stale branch pruning cannot complete.
+            }
+        }
+    }
     if (!opts.dryRun) {
         // G: persist suite name→id map so the next push avoids redundant API traversals
         if (suiteCache.size > 0) {
@@ -803,7 +956,7 @@ async function pull(config, configDir, opts = {}) {
     return pullSingle(config, configDir, opts);
 }
 async function pullSingle(config, configDir, opts) {
-    const files = await discoverFiles(config.local.include, config.local.exclude, configDir);
+    const files = filterDiscoveredFiles(await discoverFiles(config.local.include, config.local.exclude, configDir), opts.sourceFiles);
     const parsed = await parseLocalFiles(files, config, opts.tags);
     failOnParseErrors('pull', parsed.failures);
     const tests = parsed.tests;
@@ -841,7 +994,7 @@ async function pullSingle(config, configDir, opts) {
             const stepsChanged = remoteStepsText !== localStepsText;
             const descriptionChanged = (remote.description ?? '') !== (test.description ?? '');
             if (!titleChanged && !stepsChanged && !descriptionChanged) {
-                reportProgress({ action: 'skipped', filePath: test.filePath, title: test.title, azureId: test.azureId });
+                reportProgress({ action: 'skipped', filePath: test.filePath, title: test.title, azureId: test.azureId, detail: 'no changes' });
                 continue;
             }
             if (!opts.dryRun) {
@@ -904,6 +1057,14 @@ async function pullSingle(config, configDir, opts) {
                 detail: `Pull-create is not supported for local.type "${config.local.type}".`,
             });
         }
+        else if (opts.sourceFiles?.length) {
+            results.push({
+                action: 'error',
+                filePath: '',
+                title: '',
+                detail: 'Pull-create is not supported together with --source-file because partial runs cannot infer which unlinked remote tests to materialize.',
+            });
+        }
         else {
             try {
                 const remoteTcs = await (0, test_cases_1.getTestCasesInSuite)(client, config);
@@ -939,10 +1100,17 @@ async function pullSingle(config, configDir, opts) {
 }
 // ─── Status ───────────────────────────────────────────────────────────────────
 async function status(config, configDir, opts = {}) {
-    return push(config, configDir, { dryRun: true, tags: opts.tags, onProgress: opts.onProgress, onAiProgress: opts.onAiProgress, aiSummary: opts.aiSummary });
+    return push(config, configDir, {
+        dryRun: true,
+        tags: opts.tags,
+        sourceFiles: opts.sourceFiles,
+        onProgress: opts.onProgress,
+        onAiProgress: opts.onAiProgress,
+        aiSummary: opts.aiSummary,
+    });
 }
 // ─── Cache helpers ────────────────────────────────────────────────────────────
-function updateCacheEntry(cache, test, remote) {
+function updateCacheEntry(cache, test, remote, suitePathKey) {
     if (!remote.changedDate)
         return;
     cache[remote.id] = {
@@ -955,6 +1123,7 @@ function updateCacheEntry(cache, test, remote) {
         remoteDescriptionHash: (0, cache_1.hashString)(remote.description),
         changedDate: remote.changedDate,
         filePath: test.filePath,
+        suitePathKey,
     };
 }
 // ─── Apply remote changes to local file ───────────────────────────────────────
@@ -1180,7 +1349,7 @@ function buildPullMarkdownContent(tc, tagPrefix) {
  * without running push, or when TCs are created directly in Azure without a local spec.
  */
 async function detectStaleTestCases(config, configDir, opts = {}) {
-    const files = await discoverFiles(config.local.include, config.local.exclude, configDir);
+    const files = filterDiscoveredFiles(await discoverFiles(config.local.include, config.local.exclude, configDir), opts.sourceFiles);
     const parsed = await parseLocalFiles(files, config, opts.tags);
     failOnParseErrors('stale test case detection', parsed.failures);
     const tests = parsed.tests;
@@ -1211,7 +1380,7 @@ async function detectStaleTestCases(config, configDir, opts = {}) {
  *   2. Story coverage   — % of referenced User Stories that have at least one linked spec
  */
 async function coverageReport(config, configDir, opts = {}) {
-    const files = await discoverFiles(config.local.include, config.local.exclude, configDir);
+    const files = filterDiscoveredFiles(await discoverFiles(config.local.include, config.local.exclude, configDir), opts.sourceFiles);
     const parsed = await parseLocalFiles(files, config, opts.tags);
     failOnParseErrors('coverage report', parsed.failures);
     const tests = parsed.tests;