@yemi33/minions 0.1.2448 → 0.1.2449

package/watch-plugins/ado-author-prs.js

@@ -0,0 +1,336 @@
+/**
+ * watch-plugins/ado-author-prs.js — Watch an ADO repo for open PRs by author(s)
+ *
+ * Mirrors watch-plugins/gh-author-prs.js but speaks the Azure DevOps REST API
+ * via engine/ado/index.js (`adoFetch`) + engine/ado/token.js (`acquireAdoToken`).
+ *
+ * ── Target syntax ───────────────────────────────────────────────────────────
+ *   target: { projectName: 'my-project', author?: 'alice@example.com' }
+ *     → resolves `project` from state.config.projects by name. When
+ *       `author` is omitted, the plugin uses every entry in
+ *       `project.observeAuthors`. When `author` is supplied, only that
+ *       author is observed.
+ *
+ *   target: 'projectName:author' — bare colon-delimited shorthand.
+ *
+ * ── Fail-closed gate (W-mq8li79a000889fa) ──────────────────────────────────
+ * fetchEntity inspects the resolved project on every call. When the project
+ * is missing `repositoryId` (required for the ADO PR list endpoint) OR has
+ * an empty effective author list, the plugin returns an entity carrying
+ * a clear `error` string. The error propagates into the watch's
+ * `_lastState.lastError` so the dashboard surface it ("Watch errored: …")
+ * instead of silently swallowing the misconfiguration.
+ *
+ * ── Conditions ──────────────────────────────────────────────────────────────
+ *   new-pr — fires once per newly-observed open PR id. Drafts are ignored.
+ *
+ * Burst handling: same as gh-author-prs — captureState advances by exactly
+ * one new PR per tick so a burst drains losslessly across ticks (one fire
+ * per tick).
+ *
+ * ── Fetch model ─────────────────────────────────────────────────────────────
+ * checkWatches is synchronous and runs inside mutateWatches's lock callback,
+ * so the plugin maintains a module-level background-fetch cache identical
+ * to gh-author-prs. `fetchEntity` is sync: it returns the cached entity and,
+ * when the cached value is older than 60s (or absent), kicks off a
+ * background ADO REST refresh.
+ *
+ * Tests can short-circuit the background fetch entirely by pre-populating
+ * `state.adoAuthorPrs[targetKey]` with the entity shape used here
+ * (`{ prs, fetchedAt, error? }`). Tests can also override the underlying
+ * lister via `setLister(fn)` to drive the cache path.
+ *
+ * Auth: ADO tokens via `engine/ado/token.js#acquireAdoToken` (az CLI first,
+ * azureauth fallback). NEVER `az login` from this plugin — auth setup is
+ * the user's responsibility; we fail closed when the token isn't available.
+ */
+
+function ts() { return new Date().toISOString(); }
+function _warn(msg) { try { console.warn(`[${ts()}] [warn] ${msg}`); } catch {} }
+
+const CACHE_FRESHNESS_MS = 60 * 1000;
+const SEEN_NUMBERS_CAP = 500;
+
+// Module-level caches. Survive across ticks; reset on engine restart.
+const _entityCache = new Map();
+const _inFlight = new Set();
+
+// Override-able lister — default uses the real ADO REST endpoint.
+let _lister = _defaultAdoPrList;
+function setLister(fn) { _lister = typeof fn === 'function' ? fn : _defaultAdoPrList; }
+function _resetCache() { _entityCache.clear(); _inFlight.clear(); }
+
+function _findProjectByName(projects, name) {
+  if (!Array.isArray(projects) || !name) return null;
+  const needle = String(name).toLowerCase();
+  return projects.find(p => p && String(p.name || '').toLowerCase() === needle) || null;
+}
+
+function _validateTarget(target) {
+  if (typeof target === 'string') {
+    const value = target.trim();
+    if (!value) return 'target must include a project name';
+    const separator = value.indexOf(':');
+    if (separator >= 0
+        && (!value.slice(0, separator).trim() || !value.slice(separator + 1).trim())) {
+      return 'target shorthand must be "projectName:author"';
+    }
+    return null;
+  }
+  if (!target || typeof target !== 'object' || Array.isArray(target)) {
+    return 'target must be a project string or an object with projectName';
+  }
+  const projectName = target.projectName ?? target.project;
+  if (typeof projectName !== 'string' || !projectName.trim()) {
+    return 'target.projectName must be a non-empty string';
+  }
+  if (target.author !== undefined
+      && (typeof target.author !== 'string' || !target.author.trim())) {
+    return 'target.author must be a non-empty string when provided';
+  }
+  return null;
+}
+
+// Resolve { project, authors[] } from a watch target + state.config.
+// Returns { error: '...' } when the target is malformed, the project is
+// unknown, or the project is missing required fields.
+function _resolveContext(target, state) {
+  let projectName, author;
+  if (typeof target === 'string') {
+    const idx = target.indexOf(':');
+    if (idx > 0) {
+      projectName = target.slice(0, idx).trim();
+      author = target.slice(idx + 1).trim() || null;
+    } else {
+      projectName = target.trim();
+      author = null;
+    }
+  } else if (target && typeof target === 'object') {
+    projectName = String(target.projectName || target.project || '').trim();
+    author = target.author ? String(target.author).trim() : null;
+  } else {
+    return { error: 'invalid target: expected "projectName:author" or { projectName, author? }' };
+  }
+  if (!projectName) return { error: 'invalid target: projectName required' };
+
+  const project = _findProjectByName(state && state.config && state.config.projects, projectName);
+  if (!project) {
+    return { error: `unknown project "${projectName}" — not present in config.projects` };
+  }
+  if (String(project.repoHost || '').toLowerCase() !== 'ado') {
+    return { error: `project "${projectName}" is not an ADO project (repoHost=${project.repoHost})` };
+  }
+
+  const missing = [];
+  if (!String(project.repositoryId || '').trim()) missing.push('repositoryId');
+  if (!String(project.adoOrg || '').trim()) missing.push('adoOrg');
+  if (!String(project.adoProject || '').trim()) missing.push('adoProject');
+  if (missing.length > 0) {
+    return { error: `project "${projectName}" missing required field(s): ${missing.join(', ')}` };
+  }
+
+  let authors;
+  if (author) {
+    authors = [author];
+  } else {
+    authors = Array.isArray(project.observeAuthors)
+      ? project.observeAuthors.map(v => String(v || '').trim()).filter(Boolean)
+      : [];
+  }
+  if (authors.length === 0) {
+    return { error: `project "${projectName}" missing observeAuthors (and no inline author supplied in watch target)` };
+  }
+
+  return { project, authors };
+}
+
+function _targetKey(target, project) {
+  if (project && project.repositoryId) {
+    const author = (typeof target === 'object' && target.author) ? target.author : '*';
+    return `${project.repositoryId}::${author}`;
+  }
+  if (typeof target === 'string') return target;
+  try { return JSON.stringify(target); } catch { return String(target); }
+}
+
+// Default lister — uses the ADO REST endpoint via engine/ado/index.js +
+// engine/ado/token.js. Returns { prs, fetchedAt, error? }.
+async function _defaultAdoPrList(project, authors) {
+  let adoToken, adoFetch;
+  try {
+    ({ acquireAdoToken: adoToken } = require('../engine/ado/token'));
+    ({ adoFetch } = require('../engine/ado'));
+  } catch (e) {
+    return { prs: [], error: `ado-author-prs: required engine modules unavailable: ${e.message}`, fetchedAt: ts() };
+  }
+  let tokenInfo;
+  try {
+    tokenInfo = await adoToken({});
+  } catch (e) {
+    return { prs: [], error: `ado-author-prs: token acquisition failed: ${e.message}`, fetchedAt: ts() };
+  }
+  if (!tokenInfo || !tokenInfo.token) {
+    return { prs: [], error: 'ado-author-prs: no ADO token available', fetchedAt: ts() };
+  }
+
+  const orgBase = `https://dev.azure.com/${encodeURIComponent(project.adoOrg)}`;
+  const url = `${orgBase}/${encodeURIComponent(project.adoProject)}/_apis/git/repositories/${encodeURIComponent(project.repositoryId)}/pullrequests?searchCriteria.status=active&$top=200&api-version=7.1`;
+  let data;
+  try {
+    data = await adoFetch(url, tokenInfo.token, { timeout: 15000 });
+  } catch (e) {
+    return { prs: [], error: `ado-author-prs: ADO REST failed: ${e.message}`, fetchedAt: ts() };
+  }
+  const all = Array.isArray(data && data.value) ? data.value : [];
+  const authorSet = new Set(authors.map(a => a.toLowerCase()));
+  const prs = all
+    .filter(pr => {
+      if (!pr || typeof pr.pullRequestId !== 'number') return false;
+      if (pr.isDraft) return false;
+      const c = pr.createdBy || {};
+      const identifiers = [c.uniqueName, c.mailAddress, c.displayName, c.principalName, c.id]
+        .map(v => String(v || '').toLowerCase());
+      return identifiers.some(id => authorSet.has(id));
+    })
+    .map(pr => ({
+      number: pr.pullRequestId,
+      title: String(pr.title || ''),
+      url: String(pr.url || pr._links?.web?.href || ''),
+      branch: String(pr.sourceRefName || '').replace(/^refs\/heads\//, ''),
+      author: String(pr.createdBy?.uniqueName || pr.createdBy?.mailAddress || pr.createdBy?.displayName || ''),
+      createdAt: String(pr.creationDate || ''),
+      sourceCommitId: String(pr.lastMergeSourceCommit?.commitId || ''),
+      isDraft: Boolean(pr.isDraft),
+    }));
+  return { prs, fetchedAt: ts() };
+}
+
+function _scheduleRefresh(target, state, key, ctx) {
+  if (_inFlight.has(key)) return;
+  _inFlight.add(key);
+  Promise.resolve()
+    .then(() => _lister(ctx.project, ctx.authors))
+    .then((entity) => { _entityCache.set(key, entity); })
+    .catch((e) => {
+      _entityCache.set(key, { prs: [], error: e && e.message ? e.message : String(e), fetchedAt: ts() });
+    })
+    .then(() => { _inFlight.delete(key); });
+}
+
+function fetchEntity(target, state) {
+  const ctx = _resolveContext(target, state);
+  if (ctx.error) {
+    // Surface validation errors directly — never reach the network when
+    // the project shape is invalid. Tests assert this path.
+    return { prs: [], error: ctx.error, fetchedAt: ts(), _target: target };
+  }
+  const key = _targetKey(target, ctx.project);
+  // Test/external override path.
+  if (state && state.adoAuthorPrs && Object.prototype.hasOwnProperty.call(state.adoAuthorPrs, key)) {
+    const inj = state.adoAuthorPrs[key];
+    return inj ? { ...inj, _target: target, _project: ctx.project } : null;
+  }
+  const cached = _entityCache.get(key);
+  const cachedAge = cached && cached.fetchedAt
+    ? Date.now() - new Date(cached.fetchedAt).getTime()
+    : Infinity;
+  if (!cached || cachedAge > CACHE_FRESHNESS_MS) {
+    _scheduleRefresh(target, state, key, ctx);
+  }
+  return cached ? { ...cached, _target: target, _project: ctx.project } : null;
+}
+
+// captureState — same burst-drain semantics as gh-author-prs: at most one
+// new PR id advances per tick so a backlog of N opens fires once per tick
+// for N ticks rather than swallowing N-1 PRs.
+function captureState(entity, prevState) {
+  const prevNumbers = Array.isArray(prevState && prevState.numbers) ? prevState.numbers : [];
+  if (!entity) return { numbers: prevNumbers };
+  const seen = new Set(prevNumbers);
+  const currentReady = (entity.prs || [])
+    .filter(p => !p.isDraft)
+    .map(p => p.number)
+    .sort((a, b) => a - b);
+  const newOnes = currentReady.filter(n => !seen.has(n));
+  let next;
+  if (newOnes.length === 0) {
+    next = prevNumbers.slice();
+  } else {
+    next = [...seen, newOnes[0]].sort((a, b) => a - b);
+  }
+  if (next.length > SEEN_NUMBERS_CAP) {
+    next = next.slice(next.length - SEEN_NUMBERS_CAP);
+  }
+  return {
+    numbers: next,
+    lastFetchedAt: entity.fetchedAt || null,
+    lastError: entity.error || null,
+  };
+}
+
+function _firstUnseenReadyPr(entity, prevState) {
+  if (!entity) return null;
+  const prevNumbers = Array.isArray(prevState && prevState.numbers) ? prevState.numbers : [];
+  const seen = new Set(prevNumbers);
+  const candidates = (entity.prs || [])
+    .filter(p => !p.isDraft && !seen.has(p.number))
+    .sort((a, b) => a.number - b.number);
+  return candidates[0] || null;
+}
+
+function evaluate(condition, entity, prevState, target) {
+  if (condition !== 'new-pr') return { triggered: false, message: '' };
+  if (!entity) return { triggered: false, message: '' };
+  if (entity.error) return { triggered: false, message: '' };
+  const newPr = _firstUnseenReadyPr(entity, prevState);
+  if (!newPr) return { triggered: false, message: '' };
+  const projectName = (entity._project && entity._project.name)
+    || (typeof target === 'object' && target.projectName)
+    || (typeof target === 'string' && target.split(':')[0])
+    || '<unknown>';
+  return {
+    triggered: true,
+    message: `New ADO PR on ${projectName} #${newPr.number}: ${newPr.title}`,
+  };
+}
+
+function contextVars(entity, prevState, _newState) {
+  const newPr = _firstUnseenReadyPr(entity, prevState);
+  if (!newPr) return {};
+  const project = entity && entity._project;
+  return {
+    prNumber: newPr.number,
+    prTitle: newPr.title,
+    prUrl: newPr.url,
+    prBranch: newPr.branch,
+    prAuthor: newPr.author || '',
+    prHeadSha: newPr.sourceCommitId || '',
+    prCreatedAt: newPr.createdAt || '',
+    prIsDraft: false,
+    projectName: project ? project.name : '',
+    adoOrg: project ? project.adoOrg : '',
+    adoProject: project ? project.adoProject : '',
+    repositoryId: project ? project.repositoryId : '',
+  };
+}
+
+module.exports = {
+  name: 'ado-author-prs',
+  spec: {
+    label: 'ADO PRs by Author',
+    description: 'Poll an ADO repo for non-draft active PRs by configured authors. Requires project.repositoryId and project.observeAuthors (or inline author in target). Fires once per newly-observed PR id.',
+    conditions: ['new-pr'],
+    absoluteConditions: [],
+    validateTarget: _validateTarget,
+    fetchEntity,
+    captureState,
+    evaluate,
+    contextVars,
+  },
+  // Exported for tests
+  _resolveContext,
+  _targetKey,
+  _firstUnseenReadyPr,
+  setLister,
+  _resetCache,
+};