forge-workflow 0.0.9 → 0.1.0-beta.2

package/lib/issue-sync/legacy-link-bridge.js

@@ -0,0 +1,436 @@
+const {
+  createLinkStore,
+  normalizeGitHubNumber,
+  resolveCanonicalLink,
+  upsertCanonicalLink,
+} = require('./link-store.js');
+
+const SOURCE_PRECEDENCE = new Map([
+  ['githubNodeId', 0],
+  ['githubNumber', 1],
+  ['existing', 2],
+  ['externalRef', 3],
+  ['githubIssue', 4],
+  ['mapping', 5],
+  ['syncComment', 6],
+  ['descriptionUrl', 7],
+]);
+
+function precedenceFor(source) {
+  return SOURCE_PRECEDENCE.get(source) ?? Number.MAX_SAFE_INTEGER;
+}
+
+function parseExternalRef(externalRef) {
+  if (typeof externalRef !== 'string') {
+    return null;
+  }
+
+  const match = externalRef.match(/\bgh-(\d+)\b/i);
+  return match ? normalizeGitHubNumber(match[1]) : null;
+}
+
+function extractGitHubIssueUrl(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const match = value.match(/https:\/\/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/);
+  if (!match) {
+    return null;
+  }
+
+  return {
+    owner: match[1],
+    repo: match[2],
+    number: normalizeGitHubNumber(match[3]),
+    url: match[0],
+  };
+}
+
+function parseSyncComment(comment) {
+  const issueUrl = extractGitHubIssueUrl(comment?.body);
+  const githubNumber = normalizeGitHubNumber(
+    comment?.githubNumber ?? comment?.issueNumber ?? issueUrl?.number ?? parseExternalRef(comment?.body),
+  );
+
+  return {
+    forgeIssueId: comment?.forgeIssueId ?? comment?.beadsId ?? null,
+    githubNumber,
+    githubNodeId: comment?.githubNodeId ?? comment?.nodeId ?? null,
+    url: issueUrl?.url ?? null,
+  };
+}
+
+function buildSourceRecord(source, input = {}) {
+  const record = { source };
+
+  if (input.githubNumber !== null && input.githubNumber !== undefined) {
+    record.githubNumber = normalizeGitHubNumber(input.githubNumber);
+  }
+
+  if (input.githubNodeId) {
+    record.githubNodeId = input.githubNodeId;
+  }
+
+  if (input.forgeIssueId) {
+    record.forgeIssueId = input.forgeIssueId;
+  }
+
+  if (input.url) {
+    record.url = input.url;
+  }
+
+  return record;
+}
+
+function hasStructuredMappingEntry(mapping) {
+  if (!mapping || typeof mapping !== 'object' || Array.isArray(mapping)) {
+    return false;
+  }
+
+  return [
+    'forgeIssueId',
+    'githubNumber',
+    'issueNumber',
+    'githubNodeId',
+    'nodeId',
+    'url',
+  ].some((key) => Object.hasOwn(mapping, key));
+}
+
+function collectMappingSources(mapping, forgeIssueId, explicitGitHubNumber) {
+  if (mapping === undefined || mapping === null) {
+    return [];
+  }
+
+  if (typeof mapping === 'object' && !Array.isArray(mapping)) {
+    if (hasStructuredMappingEntry(mapping)) {
+      return [buildSourceRecord('mapping', {
+        forgeIssueId: mapping.forgeIssueId ?? forgeIssueId,
+        githubNumber: mapping.githubNumber ?? mapping.issueNumber,
+        githubNodeId: mapping.githubNodeId ?? mapping.nodeId,
+        url: mapping.url,
+      })];
+    }
+
+    const sources = [];
+
+    for (const [issueNumber, beadsId] of Object.entries(mapping)) {
+      const githubNumber = normalizeGitHubNumber(issueNumber);
+      if (githubNumber === null || typeof beadsId !== 'string' || beadsId.length === 0) {
+        continue;
+      }
+
+      if (forgeIssueId && beadsId === forgeIssueId) {
+        sources.push(buildSourceRecord('mapping', {
+          forgeIssueId: beadsId,
+          githubNumber,
+        }));
+        continue;
+      }
+
+      if (!forgeIssueId && explicitGitHubNumber !== null && githubNumber === explicitGitHubNumber) {
+        sources.push(buildSourceRecord('mapping', {
+          forgeIssueId: beadsId,
+          githubNumber,
+        }));
+      }
+    }
+
+    return sources;
+  }
+
+  return [buildSourceRecord('mapping', {
+    forgeIssueId,
+    githubNumber: mapping,
+  })];
+}
+
+function collectLegacySources(legacyHints) {
+  const sources = [];
+  const forgeIssueId = legacyHints.forgeIssueId ?? null;
+
+  const explicitGithub = legacyHints.github ?? {};
+  if (explicitGithub.nodeId) {
+    sources.push(buildSourceRecord('githubNodeId', {
+      forgeIssueId,
+      githubNodeId: explicitGithub.nodeId,
+      githubNumber: explicitGithub.number,
+      url: explicitGithub.url,
+    }));
+  } else if (explicitGithub.number) {
+    sources.push(buildSourceRecord('githubNumber', {
+      forgeIssueId,
+      githubNumber: explicitGithub.number,
+      url: explicitGithub.url,
+    }));
+  }
+
+  sources.push(...collectMappingSources(
+    legacyHints.mapping,
+    forgeIssueId,
+    normalizeGitHubNumber(explicitGithub.number),
+  ));
+
+  const githubIssueState = legacyHints.githubIssue ?? legacyHints.github_issue;
+  if (githubIssueState !== undefined && githubIssueState !== null) {
+    if (typeof githubIssueState === 'object') {
+      sources.push(buildSourceRecord('githubIssue', {
+        forgeIssueId: githubIssueState.forgeIssueId ?? forgeIssueId,
+        githubNumber: githubIssueState.githubNumber ?? githubIssueState.issueNumber,
+        githubNodeId: githubIssueState.githubNodeId ?? githubIssueState.nodeId,
+        url: githubIssueState.url,
+      }));
+    } else {
+      sources.push(buildSourceRecord('githubIssue', {
+        forgeIssueId,
+        githubNumber: githubIssueState,
+      }));
+    }
+  }
+
+  for (const comment of legacyHints.syncComments ?? []) {
+    const parsed = parseSyncComment(comment);
+    sources.push(buildSourceRecord('syncComment', {
+      forgeIssueId: parsed.forgeIssueId ?? forgeIssueId,
+      githubNumber: parsed.githubNumber,
+      githubNodeId: parsed.githubNodeId,
+      url: parsed.url,
+    }));
+  }
+
+  const externalRefNumber = parseExternalRef(legacyHints.externalRef);
+  if (externalRefNumber !== null) {
+    sources.push(buildSourceRecord('externalRef', {
+      forgeIssueId,
+      githubNumber: externalRefNumber,
+    }));
+  }
+
+  const descriptionMatch = extractGitHubIssueUrl(legacyHints.description ?? legacyHints.descriptionUrl);
+  if (descriptionMatch) {
+    sources.push(buildSourceRecord('descriptionUrl', {
+      forgeIssueId,
+      githubNumber: descriptionMatch.number,
+      url: descriptionMatch.url,
+    }));
+  }
+
+  return sources.filter((source) =>
+    source.forgeIssueId || source.githubNodeId || source.githubNumber || source.url);
+}
+
+function findExistingLink(store, legacyHints, sources) {
+  const forgeIssueId = legacyHints.forgeIssueId ?? null;
+
+  if (forgeIssueId) {
+    const existing = resolveCanonicalLink(store, { forgeIssueId });
+    if (existing) {
+      return existing;
+    }
+  }
+
+  for (const source of sources) {
+    if (source.githubNodeId) {
+      const existing = resolveCanonicalLink(store, { githubNodeId: source.githubNodeId });
+      if (existing) {
+        return existing;
+      }
+    }
+
+    if (source.githubNumber) {
+      const existing = resolveCanonicalLink(store, { githubNumber: source.githubNumber });
+      if (existing) {
+        return existing;
+      }
+    }
+  }
+
+  return null;
+}
+
+function pickPreferredCandidate(candidates, fieldName) {
+  const fieldKey = fieldName === 'github.nodeId' ? 'githubNodeId' : 'githubNumber';
+  const filtered = candidates.filter((candidate) => candidate[fieldKey] !== null && candidate[fieldKey] !== undefined);
+
+  if (filtered.length === 0) {
+    return null;
+  }
+
+  filtered.sort((left, right) => precedenceFor(left.source) - precedenceFor(right.source));
+  return filtered[0];
+}
+
+function buildFieldDriftDiagnostic(candidates, fieldName, selectedCandidate) {
+  if (!selectedCandidate) {
+    return [];
+  }
+
+  const fieldKey = fieldName === 'github.nodeId' ? 'githubNodeId' : 'githubNumber';
+  const conflicts = [];
+  const seenValues = new Set();
+
+  for (const candidate of candidates) {
+    if (candidate[fieldKey] === null || candidate[fieldKey] === undefined) {
+      continue;
+    }
+
+    if (candidate[fieldKey] === selectedCandidate[fieldKey]) {
+      continue;
+    }
+
+    const key = `${candidate.source}:${candidate[fieldKey]}`;
+    if (seenValues.has(key)) {
+      continue;
+    }
+
+    seenValues.add(key);
+    conflicts.push({
+      source: candidate.source,
+      value: candidate[fieldKey],
+    });
+  }
+
+  if (conflicts.length === 0) {
+    return [];
+  }
+
+  return [{
+    type: 'legacy-link-drift',
+    field: fieldName,
+    selected: {
+      source: selectedCandidate.source,
+      value: selectedCandidate[fieldKey],
+    },
+    conflicts,
+  }];
+}
+
+function buildDriftDiagnostics(candidates, selectedNodeCandidate, selectedNumberCandidate) {
+  return [
+    ...buildFieldDriftDiagnostic(candidates, 'github.nodeId', selectedNodeCandidate),
+    ...buildFieldDriftDiagnostic(candidates, 'github.number', selectedNumberCandidate),
+  ];
+}
+
+function chooseCanonicalUrl(existingLink, sources, selectedNumber) {
+  if (existingLink?.github?.url && existingLink.github.number === selectedNumber) {
+    return existingLink.github.url;
+  }
+
+  for (const source of sources) {
+    if (source.url && source.githubNumber === selectedNumber) {
+      return source.url;
+    }
+  }
+
+  return null;
+}
+
+function shouldSeedLegacyMappingEntries(legacyHints = {}) {
+  const mapping = legacyHints.mapping;
+  const explicitGithub = legacyHints.github ?? {};
+
+  return (
+    !legacyHints.forgeIssueId &&
+    mapping &&
+    typeof mapping === 'object' &&
+    !Array.isArray(mapping) &&
+    !hasStructuredMappingEntry(mapping) &&
+    !explicitGithub.nodeId &&
+    normalizeGitHubNumber(explicitGithub.number) === null &&
+    legacyHints.githubIssue == null &&
+    legacyHints.github_issue == null &&
+    (legacyHints.syncComments ?? []).length === 0 &&
+    !legacyHints.externalRef &&
+    !legacyHints.description &&
+    !legacyHints.descriptionUrl
+  );
+}
+
+function seedLegacyMappingEntries(store, mapping) {
+  const links = [];
+  const diagnostics = [];
+
+  for (const [issueNumber, forgeIssueId] of Object.entries(mapping)) {
+    if (typeof forgeIssueId !== 'string' || forgeIssueId.length === 0) {
+      continue;
+    }
+
+    const githubNumber = normalizeGitHubNumber(issueNumber);
+    if (githubNumber === null) {
+      continue;
+    }
+
+    const result = bridgeLegacyLinkHints(
+      {
+        forgeIssueId,
+        mapping: githubNumber,
+      },
+      { store },
+    );
+
+    if (result.link) {
+      links.push(result.link);
+    }
+
+    if (Array.isArray(result.diagnostics)) {
+      diagnostics.push(...result.diagnostics);
+    }
+  }
+
+  return { links, diagnostics };
+}
+
+function bridgeLegacyLinkHints(legacyHints, options = {}) {
+  const store = options.store ?? createLinkStore();
+  if (shouldSeedLegacyMappingEntries(legacyHints)) {
+    const { links, diagnostics } = seedLegacyMappingEntries(store, legacyHints.mapping);
+    return {
+      link: links.at(-1) ?? null,
+      diagnostics,
+      links,
+    };
+  }
+
+  const sources = collectLegacySources(legacyHints);
+  const existingLink = findExistingLink(store, legacyHints, sources);
+
+  const candidates = existingLink ? [
+    buildSourceRecord('existing', {
+      forgeIssueId: existingLink.forgeIssueId,
+      githubNumber: existingLink.github.number,
+      githubNodeId: existingLink.github.nodeId,
+      url: existingLink.github.url,
+    }),
+    ...sources,
+  ] : sources;
+
+  const selectedNodeCandidate = pickPreferredCandidate(candidates, 'github.nodeId');
+  const selectedNumberCandidate = pickPreferredCandidate(candidates, 'github.number');
+  const diagnostics = buildDriftDiagnostics(candidates, selectedNodeCandidate, selectedNumberCandidate);
+
+  const link = upsertCanonicalLink(store, {
+    forgeIssueId: legacyHints.forgeIssueId ?? existingLink?.forgeIssueId ?? null,
+    github: {
+      nodeId: selectedNodeCandidate?.githubNodeId ?? existingLink?.github?.nodeId ?? null,
+      number: selectedNumberCandidate?.githubNumber ?? existingLink?.github?.number ?? null,
+      url: chooseCanonicalUrl(existingLink, sources, selectedNumberCandidate?.githubNumber ?? null),
+    },
+    sources,
+    diagnostics,
+  });
+
+  return {
+    link,
+    diagnostics: link.diagnostics,
+  };
+}
+
+module.exports = {
+  bridgeLegacyLinkHints,
+  buildSourceRecord,
+  collectLegacySources,
+  extractGitHubIssueUrl,
+  parseExternalRef,
+};

package/lib/issue-sync/link-store.js

@@ -0,0 +1,292 @@
+function createDefaultCanonicalLink() {
+  return {
+    forgeIssueId: null,
+    github: {
+      nodeId: null,
+      number: null,
+      url: null,
+    },
+    sources: [],
+    diagnostics: [],
+  };
+}
+
+function cloneValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(cloneValue);
+  }
+
+  if (value && typeof value === 'object') {
+    const copy = {};
+
+    for (const [key, nestedValue] of Object.entries(value)) {
+      copy[key] = cloneValue(nestedValue);
+    }
+
+    return copy;
+  }
+
+  return value;
+}
+
+function normalizeGitHubNumber(value) {
+  if (value === null || value === undefined || value === '') {
+    return null;
+  }
+
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
+function buildCanonicalLink(input = {}) {
+  const link = createDefaultCanonicalLink();
+  const github = input.github ?? {};
+
+  if (input.forgeIssueId) {
+    link.forgeIssueId = input.forgeIssueId;
+  }
+
+  if (github.nodeId) {
+    link.github.nodeId = github.nodeId;
+  }
+
+  link.github.number = normalizeGitHubNumber(github.number);
+
+  if (github.url) {
+    link.github.url = github.url;
+  }
+
+  if (Array.isArray(input.sources)) {
+    link.sources = input.sources.map(cloneValue);
+  }
+
+  if (Array.isArray(input.diagnostics)) {
+    link.diagnostics = input.diagnostics.map(cloneValue);
+  }
+
+  return link;
+}
+
+function getLinkPriority(link) {
+  if (link.github.nodeId) {
+    return 0;
+  }
+
+  if (link.github.number !== null) {
+    return 1;
+  }
+
+  if (link.forgeIssueId) {
+    return 2;
+  }
+
+  return 3;
+}
+
+function createLinkStore(initialLinks = []) {
+  const store = {
+    records: [],
+    byForgeIssueId: new Map(),
+    byGitHubNodeId: new Map(),
+    byGitHubNumber: new Map(),
+  };
+
+  for (const link of initialLinks) {
+    upsertCanonicalLink(store, link);
+  }
+
+  return store;
+}
+
+function setIndexValue(index, key, record) {
+  if (key !== null && key !== undefined && key !== '') {
+    index.set(key, record);
+  }
+}
+
+function indexRecord(store, record) {
+  setIndexValue(store.byForgeIssueId, record.forgeIssueId, record);
+  setIndexValue(store.byGitHubNodeId, record.github.nodeId, record);
+  setIndexValue(store.byGitHubNumber, record.github.number, record);
+}
+
+function removeRecord(store, record) {
+  store.records = store.records.filter((candidate) => candidate !== record);
+
+  if (record.forgeIssueId) {
+    store.byForgeIssueId.delete(record.forgeIssueId);
+  }
+
+  if (record.github.nodeId) {
+    store.byGitHubNodeId.delete(record.github.nodeId);
+  }
+
+  if (record.github.number !== null) {
+    store.byGitHubNumber.delete(record.github.number);
+  }
+}
+
+function mergeUniqueEntries(existingEntries, incomingEntries) {
+  const merged = [];
+  const seen = new Set();
+
+  for (const entry of [...existingEntries, ...incomingEntries]) {
+    const key = JSON.stringify(entry);
+    if (seen.has(key)) {
+      continue;
+    }
+
+    seen.add(key);
+    merged.push(cloneValue(entry));
+  }
+
+  return merged;
+}
+
+function collectMatchedRecords(store, link) {
+  const matches = new Map();
+
+  function registerMatch(record, priority) {
+    if (!record) {
+      return;
+    }
+
+    const existingPriority = matches.get(record);
+    if (existingPriority === undefined || priority < existingPriority) {
+      matches.set(record, priority);
+    }
+  }
+
+  if (link.forgeIssueId && store.byForgeIssueId.has(link.forgeIssueId)) {
+    registerMatch(store.byForgeIssueId.get(link.forgeIssueId), 0);
+  }
+
+  if (link.github.nodeId && store.byGitHubNodeId.has(link.github.nodeId)) {
+    registerMatch(store.byGitHubNodeId.get(link.github.nodeId), 1);
+  }
+
+  if (link.github.number !== null && store.byGitHubNumber.has(link.github.number)) {
+    registerMatch(store.byGitHubNumber.get(link.github.number), 2);
+  }
+
+  return [...matches.entries()].map(([record, priority]) => ({ record, priority }));
+}
+
+function mergeCandidateEntries(candidates, fieldName) {
+  let mergedEntries = [];
+
+  for (const candidate of candidates) {
+    mergedEntries = mergeUniqueEntries(mergedEntries, candidate.record[fieldName] ?? []);
+  }
+
+  return mergedEntries;
+}
+
+function mergeCanonicalLinkCandidates(candidates) {
+  const mergedRecord = createDefaultCanonicalLink();
+
+  for (const candidate of candidates) {
+    const { record } = candidate;
+
+    if (mergedRecord.forgeIssueId === null && record.forgeIssueId) {
+      mergedRecord.forgeIssueId = record.forgeIssueId;
+    }
+
+    if (mergedRecord.github.nodeId === null && record.github.nodeId) {
+      mergedRecord.github.nodeId = record.github.nodeId;
+    }
+
+    if (mergedRecord.github.number === null && record.github.number !== null) {
+      mergedRecord.github.number = record.github.number;
+    }
+
+    if (mergedRecord.github.url === null && record.github.url) {
+      mergedRecord.github.url = record.github.url;
+    }
+  }
+
+  mergedRecord.sources = mergeCandidateEntries(candidates, 'sources');
+  mergedRecord.diagnostics = mergeCandidateEntries(candidates, 'diagnostics');
+
+  return mergedRecord;
+}
+
+function buildMergeCandidates(store, matchedRecords, incomingRecord) {
+  const existingOrder = new Map(store.records.map((record, index) => [record, index]));
+  const candidates = matchedRecords.map(({ record, priority }) => ({
+    record,
+    priority,
+    incoming: false,
+    order: existingOrder.get(record) ?? Number.MAX_SAFE_INTEGER,
+  }));
+
+  candidates.push({
+    record: incomingRecord,
+    priority: getLinkPriority(incomingRecord),
+    incoming: true,
+    order: Number.MAX_SAFE_INTEGER,
+  });
+
+  candidates.sort((left, right) => {
+    if (left.priority !== right.priority) {
+      return left.priority - right.priority;
+    }
+
+    if (left.incoming !== right.incoming) {
+      return left.incoming ? -1 : 1;
+    }
+
+    return left.order - right.order;
+  });
+
+  return candidates;
+}
+
+function upsertCanonicalLink(store, input) {
+  const incomingRecord = buildCanonicalLink(input);
+  const matchedRecords = collectMatchedRecords(store, incomingRecord);
+  const mergedRecord = mergeCanonicalLinkCandidates(
+    buildMergeCandidates(store, matchedRecords, incomingRecord),
+  );
+
+  for (const { record } of matchedRecords) {
+    removeRecord(store, record);
+  }
+
+  store.records.push(mergedRecord);
+  indexRecord(store, mergedRecord);
+
+  return mergedRecord;
+}
+
+function resolveCanonicalLink(store, lookup = {}) {
+  if (lookup.forgeIssueId && store.byForgeIssueId.has(lookup.forgeIssueId)) {
+    return store.byForgeIssueId.get(lookup.forgeIssueId);
+  }
+
+  if (lookup.githubNodeId && store.byGitHubNodeId.has(lookup.githubNodeId)) {
+    return store.byGitHubNodeId.get(lookup.githubNodeId);
+  }
+
+  const githubNumber = normalizeGitHubNumber(lookup.githubNumber);
+  if (githubNumber !== null && store.byGitHubNumber.has(githubNumber)) {
+    return store.byGitHubNumber.get(githubNumber);
+  }
+
+  return null;
+}
+
+function listCanonicalLinks(store) {
+  return store.records.map(cloneValue);
+}
+
+module.exports = {
+  buildCanonicalLink,
+  createDefaultCanonicalLink,
+  createLinkStore,
+  getLinkPriority,
+  listCanonicalLinks,
+  normalizeGitHubNumber,
+  resolveCanonicalLink,
+  upsertCanonicalLink,
+};