specrails-desktop 2.3.0 → 2.4.0

package/server/dist/jira/jira-status-resolver.js

@@ -0,0 +1,211 @@
+"use strict";
+// Status / transition resolution — the hard part of the integration.
+//
+// Jira issues have no settable `status`; you must apply workflow-gated
+// transitions, and the customer's workflow is arbitrary. The 4 logical Specrails
+// states map onto N customer statuses across only 3 stable categories
+// (new / indeterminate / done). Strategy:
+//   1. Explicit per-project status map (user picks the target status) wins.
+//   2. Category fallback anchored on `statusCategory.key` (never the localizable
+//      status NAME), with a cancel/ship lexicon to disambiguate the `done`
+//      category (e.g. `Won't Do` vs `Released`).
+//   3. BFS transition walk for forward-only workflows where there is no direct
+//      edge to the target category.
+//
+// This module is PURE: the walker takes async callbacks (getTransitions /
+// applyTransition) so it is fully testable without HTTP.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.targetCategoryFor = targetCategoryFor;
+exports.categoryRank = categoryRank;
+exports.pickDirectTransition = pickDirectTransition;
+exports.pickProgressTransition = pickProgressTransition;
+exports.buildTransitionFields = buildTransitionFields;
+exports.walkToCategory = walkToCategory;
+const CANCEL_LEXICON = ['won\'t do', 'wont do', 'cancelled', 'canceled', 'rejected', 'abandoned', 'invalid', 'duplicate', 'declined'];
+const SHIP_LEXICON = ['done', 'closed', 'released', 'resolved', 'complete', 'completed', 'shipped', 'merged'];
+function targetCategoryFor(state) {
+    switch (state) {
+        case 'todo':
+            return 'new';
+        case 'in_progress':
+            return 'indeterminate';
+        case 'done':
+        case 'cancelled':
+            return 'done';
+    }
+}
+function categoryRank(cat) {
+    return cat === 'new' ? 0 : cat === 'indeterminate' ? 1 : 2;
+}
+function nameMatches(name, lexicon) {
+    if (!name)
+        return false;
+    const n = name.toLowerCase();
+    return lexicon.some((w) => n.includes(w));
+}
+function transitionCategory(t) {
+    const k = t.to.statusCategory?.key;
+    if (k === 'new' || k === 'indeterminate' || k === 'done')
+        return k;
+    return null;
+}
+/**
+ * Pick the best transition that lands directly in the target category.
+ * - Explicit map (status id or name) wins.
+ * - Else category match, disambiguated by lexicon for the `done` category.
+ * Returns null when no transition lands directly in the target category.
+ */
+function pickDirectTransition(transitions, state, explicitTarget) {
+    if (explicitTarget) {
+        const t = transitions.find((tr) => tr.to.id === explicitTarget || tr.to.name.toLowerCase() === explicitTarget.toLowerCase() || tr.id === explicitTarget);
+        if (t)
+            return t;
+    }
+    const target = targetCategoryFor(state);
+    const candidates = transitions.filter((t) => transitionCategory(t) === target);
+    if (candidates.length === 0)
+        return null;
+    if (target !== 'done')
+        return candidates[0];
+    // Disambiguate the `done` category: cancelled prefers the cancel lexicon and
+    // avoids ship words; done/success prefers ship words and avoids cancel words.
+    if (state === 'cancelled') {
+        const cancel = candidates.find((t) => nameMatches(t.to.name, CANCEL_LEXICON));
+        if (cancel)
+            return cancel;
+        // No explicit cancel status → do NOT fall back to a generic Done (that would
+        // mark a cancelled spec as shipped). Signal "no suitable transition".
+        return null;
+    }
+    // success
+    const ship = candidates.find((t) => nameMatches(t.to.name, SHIP_LEXICON) && !nameMatches(t.to.name, CANCEL_LEXICON));
+    if (ship)
+        return ship;
+    const nonCancel = candidates.find((t) => !nameMatches(t.to.name, CANCEL_LEXICON));
+    return nonCancel ?? candidates[0];
+}
+/**
+ * Pick a transition that moves the issue closer to the target category (used by
+ * the BFS walk when no direct transition exists). Returns the edge whose target
+ * category is strictly closer (in rank distance) to the goal, never overshooting
+ * past it, preferring the smallest forward step.
+ */
+function pickProgressTransition(transitions, currentCategory, targetCategory, visitedStatusIds) {
+    const goal = categoryRank(targetCategory);
+    const cur = categoryRank(currentCategory);
+    const dir = Math.sign(goal - cur); // +1 forward, -1 backward
+    if (dir === 0)
+        return null;
+    let best = null;
+    let bestRank = cur;
+    for (const t of transitions) {
+        if (visitedStatusIds.has(t.to.id))
+            continue;
+        const cat = transitionCategory(t);
+        if (!cat)
+            continue;
+        const rank = categoryRank(cat);
+        // Must move in the goal direction and not overshoot.
+        const movesTowardGoal = dir > 0 ? rank > cur && rank <= goal : rank < cur && rank >= goal;
+        if (!movesTowardGoal)
+            continue;
+        // Prefer the edge that gets us furthest toward the goal without overshooting.
+        if (best === null || (dir > 0 ? rank > bestRank : rank < bestRank)) {
+            best = t;
+            bestRank = rank;
+        }
+    }
+    return best;
+}
+/**
+ * Build the `fields` payload for a transition that has a screen. Sets
+ * `resolution` (Done for success / a cancel value for cancelled) only when it is
+ * on the transition screen. If a required field with no default cannot be
+ * synthesised, returns `blockedReason` so the caller dead-letters instead of
+ * guessing values.
+ */
+function buildTransitionFields(transition, state) {
+    const screenFields = transition.fields ?? {};
+    const out = {};
+    for (const [key, field] of Object.entries(screenFields)) {
+        if (key === 'resolution') {
+            const allowed = field.allowedValues ?? [];
+            const wantCancel = state === 'cancelled';
+            const pick = wantCancel
+                ? allowed.find((v) => nameMatches(v.name ?? v.value, CANCEL_LEXICON)) ?? allowed[0]
+                : allowed.find((v) => nameMatches(v.name ?? v.value, SHIP_LEXICON)) ?? allowed[0];
+            if (pick)
+                out.resolution = pick.id ? { id: pick.id } : { name: pick.name ?? pick.value };
+            continue;
+        }
+        // Any OTHER required field without a default that we cannot synthesise blocks us.
+        if (field.required && !field.hasDefaultValue) {
+            return { blockedReason: `transition requires field "${field.name ?? key}" with no default` };
+        }
+    }
+    return Object.keys(out).length > 0 ? { fields: out } : {};
+}
+/**
+ * Walk the transition graph from the current category to the target category for
+ * `state`, applying edges per hop (you can only see the current status's
+ * outgoing edges). Idempotency-first: if already in the target category, no-op.
+ */
+async function walkToCategory(args) {
+    const target = targetCategoryFor(args.state);
+    if (args.currentCategory === target)
+        return { status: 'noop' };
+    const maxHops = args.maxHops ?? 5;
+    const visited = new Set();
+    const applied = [];
+    let currentCategory = args.currentCategory;
+    for (let hop = 0; hop < maxHops; hop++) {
+        let transitions;
+        try {
+            transitions = await args.getTransitions();
+        }
+        catch (err) {
+            return { status: 'error', reason: err instanceof Error ? err.message : String(err) };
+        }
+        // Try a direct transition into the target category first.
+        const direct = pickDirectTransition(transitions, args.state, args.explicitTarget);
+        if (direct) {
+            const plan = buildTransitionFields(direct, args.state);
+            if (plan.blockedReason)
+                return { status: 'blocked', reason: plan.blockedReason };
+            try {
+                await args.applyTransition(direct, plan);
+            }
+            catch (err) {
+                return { status: 'error', reason: err instanceof Error ? err.message : String(err) };
+            }
+            applied.push(direct.id);
+            return { status: 'applied', finalCategory: target, transitions: applied };
+        }
+        // No direct edge → step toward the target category.
+        const step = pickProgressTransition(transitions, currentCategory, target, visited);
+        if (!step) {
+            return {
+                status: 'no_path',
+                reason: `no workflow transition from category "${currentCategory}" toward "${target}"`,
+            };
+        }
+        const plan = buildTransitionFields(step, args.state);
+        if (plan.blockedReason)
+            return { status: 'blocked', reason: plan.blockedReason };
+        try {
+            await args.applyTransition(step, plan);
+        }
+        catch (err) {
+            return { status: 'error', reason: err instanceof Error ? err.message : String(err) };
+        }
+        applied.push(step.id);
+        visited.add(step.to.id);
+        const stepCat = transitionCategory(step);
+        if (stepCat)
+            currentCategory = stepCat;
+        if (currentCategory === target) {
+            return { status: 'applied', finalCategory: target, transitions: applied };
+        }
+    }
+    return { status: 'no_path', reason: `target category "${target}" not reached within ${maxHops} hops` };
+}