forge-workflow 0.0.9 → 0.0.10

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,
+};

package/lib/issue-sync/project-github.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const { isSharedField } = require('./authority.js');
+
+const FLAG_TO_SHARED_FIELD = new Map([
+  ['--title', 'shared.title'],
+  ['--body', 'shared.body'],
+  ['--state', 'shared.state'],
+  ['--assignee', 'shared.assignees'],
+  ['--assignees', 'shared.assignees'],
+  ['--label', 'shared.labels'],
+  ['--labels', 'shared.labels'],
+  ['--milestone', 'shared.milestone'],
+  ['--claim', 'shared.assignees'],
+]);
+
+const OPERATIONS_WITH_DEFAULT_SHARED_FIELDS = new Map([
+  ['close', ['shared.state']],
+]);
+
+function uniquePush(items, value) {
+  if (value && !items.includes(value)) {
+    items.push(value);
+  }
+}
+
+function isHelpInvocation(args = []) {
+  return Array.isArray(args) && args.some(arg => arg === '--help' || arg === '-h');
+}
+
+function appendDefaultSharedFields(operation, fieldPaths) {
+  for (const defaultField of OPERATIONS_WITH_DEFAULT_SHARED_FIELDS.get(operation) || []) {
+    if (isSharedField(defaultField)) {
+      uniquePush(fieldPaths, defaultField);
+    }
+  }
+}
+
+function inferCreateTitleField(operation, args = []) {
+  if (operation !== 'create' || !Array.isArray(args) || args.length === 0) {
+    return null;
+  }
+
+  const firstNonFlagArg = args.find(arg => typeof arg === 'string' && !arg.startsWith('-'));
+  if (firstNonFlagArg === undefined) {
+    return null;
+  }
+
+  return 'shared.title';
+}
+
+function collectSharedFieldsFromFlags(args = []) {
+  const fieldPaths = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (typeof arg !== 'string') {
+      continue;
+    }
+
+    const flagKey = arg.startsWith('--') ? arg.split('=')[0] : arg;
+    const fieldPath = FLAG_TO_SHARED_FIELD.get(flagKey);
+    if (!fieldPath || !isSharedField(fieldPath)) {
+      continue;
+    }
+
+    uniquePush(fieldPaths, fieldPath);
+
+    if (flagKey === '--claim') {
+      continue;
+    }
+
+    if (flagKey.startsWith('--') && !arg.includes('=')) {
+      index += 1;
+    }
+  }
+
+  return fieldPaths;
+}
+
+function collectSharedFieldPaths(operation, args = []) {
+  if (typeof operation !== 'string' || operation.length === 0) {
+    return [];
+  }
+
+  if (isHelpInvocation(args)) {
+    return [];
+  }
+
+  const fieldPaths = [];
+  appendDefaultSharedFields(operation, fieldPaths);
+
+  if (!Array.isArray(args)) {
+    return fieldPaths;
+  }
+
+  uniquePush(fieldPaths, inferCreateTitleField(operation, args));
+  for (const fieldPath of collectSharedFieldsFromFlags(args)) {
+    uniquePush(fieldPaths, fieldPath);
+  }
+
+  return fieldPaths;
+}
+
+function createGitHubProjectionPlan(operation, args = []) {
+  const fieldPaths = collectSharedFieldPaths(operation, args);
+
+  if (fieldPaths.length === 0) {
+    return null;
+  }
+
+  return {
+    operation,
+    args: Array.isArray(args) ? [...args] : [],
+    fieldPaths,
+  };
+}
+
+module.exports = {
+  collectSharedFieldPaths,
+  createGitHubProjectionPlan,
+  isHelpInvocation,
+};

package/lib/issue-sync/reconcile.js

@@ -0,0 +1,195 @@
+'use strict';
+
+const { buildSharedIssueRecord } = require('./schema.js');
+const {
+  GITHUB_OWNED_FIELD_PATHS,
+  cloneValue,
+} = require('./github-pull.js');
+
+const MAX_DRIFT_HISTORY = 50;
+
+function readField(record, fieldPath) {
+  switch (fieldPath) {
+    case 'github.number':
+      return record.github.number;
+    case 'github.nodeId':
+      return record.github.nodeId;
+    case 'github.url':
+      return record.github.url;
+    case 'shared.title':
+      return record.shared.title;
+    case 'shared.body':
+      return record.shared.body;
+    case 'shared.state':
+      return record.shared.state;
+    case 'shared.assignees':
+      return record.shared.assignees;
+    case 'shared.labels':
+      return record.shared.labels;
+    case 'shared.milestone':
+      return record.shared.milestone;
+    case 'sync.remoteUpdatedAt':
+      return record.sync.remoteUpdatedAt;
+    default:
+      return undefined;
+  }
+}
+
+function writeField(record, fieldPath, value) {
+  switch (fieldPath) {
+    case 'github.number':
+      record.github.number = value;
+      break;
+    case 'github.nodeId':
+      record.github.nodeId = value;
+      break;
+    case 'github.url':
+      record.github.url = value;
+      break;
+    case 'shared.title':
+      record.shared.title = value;
+      break;
+    case 'shared.body':
+      record.shared.body = value;
+      break;
+    case 'shared.state':
+      record.shared.state = value;
+      break;
+    case 'shared.assignees':
+      record.shared.assignees = value;
+      break;
+    case 'shared.labels':
+      record.shared.labels = value;
+      break;
+    case 'shared.milestone':
+      record.shared.milestone = value;
+      break;
+    case 'sync.remoteUpdatedAt':
+      record.sync.remoteUpdatedAt = value;
+      break;
+    default:
+      break;
+  }
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function deepEqual(left, right) {
+  if (left === right) {
+    return true;
+  }
+
+  if (Array.isArray(left) && Array.isArray(right)) {
+    if (left.length !== right.length) {
+      return false;
+    }
+
+    for (let index = 0; index < left.length; index += 1) {
+      if (!deepEqual(left[index], right[index])) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  if (isPlainObject(left) && isPlainObject(right)) {
+    const leftKeys = Object.keys(left);
+    const rightKeys = Object.keys(right);
+
+    if (leftKeys.length !== rightKeys.length) {
+      return false;
+    }
+
+    for (const key of leftKeys) {
+      if (!Object.hasOwn(right, key) || !deepEqual(left[key], right[key])) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  return false;
+}
+
+function createDriftDiagnostic(field, localValue, remoteValue) {
+  return {
+    type: 'github-shared-drift',
+    field,
+    localValue: cloneValue(localValue),
+    remoteValue: cloneValue(remoteValue),
+  };
+}
+
+function buildMaterializedIssueSnapshot(record) {
+  const snapshot = cloneValue(record);
+
+  if (snapshot?.cache) {
+    snapshot.cache.materializedIssue = null;
+  }
+
+  return snapshot;
+}
+
+function mergeDriftDiagnostics(existingDiagnostics = [], newDiagnostics = []) {
+  const merged = [];
+  const seen = new Set();
+
+  for (const diagnostic of [...existingDiagnostics, ...newDiagnostics]) {
+    const clonedDiagnostic = cloneValue(diagnostic);
+    const key = JSON.stringify(clonedDiagnostic);
+    if (seen.has(key)) {
+      continue;
+    }
+
+    seen.add(key);
+    merged.push(clonedDiagnostic);
+  }
+
+  return merged.slice(-MAX_DRIFT_HISTORY);
+}
+
+function reconcileSharedIssueRecord(localRecord = {}, remoteSnapshot = {}, options = {}) {
+  const existingRecord = buildSharedIssueRecord(localRecord);
+  const remoteRecord = buildSharedIssueRecord(remoteSnapshot);
+  const reconciledRecord = buildSharedIssueRecord(existingRecord);
+  const diagnostics = [];
+
+  for (const fieldPath of GITHUB_OWNED_FIELD_PATHS) {
+    const localValue = readField(existingRecord, fieldPath);
+    const remoteValue = readField(remoteRecord, fieldPath);
+
+    if (!deepEqual(localValue, remoteValue)) {
+      diagnostics.push(createDriftDiagnostic(fieldPath, localValue, remoteValue));
+    }
+
+    writeField(reconciledRecord, fieldPath, cloneValue(remoteValue));
+  }
+
+  // Some import/materialization flows need to retain the last local pull
+  // watermark instead of overwriting it with the fresh GitHub timestamp.
+  if (options.preserveRemoteUpdatedAt === false && existingRecord.sync.remoteUpdatedAt !== null) {
+    reconciledRecord.sync.remoteUpdatedAt = existingRecord.sync.remoteUpdatedAt;
+  }
+
+  reconciledRecord.sync.drift = mergeDriftDiagnostics(existingRecord.sync.drift ?? [], diagnostics);
+  reconciledRecord.cache.githubSnapshot = cloneValue(remoteSnapshot);
+  reconciledRecord.cache.materializedIssue = buildMaterializedIssueSnapshot(reconciledRecord);
+
+  return {
+    record: reconciledRecord,
+    diagnostics,
+  };
+}
+
+module.exports = {
+  buildMaterializedIssueSnapshot,
+  createDriftDiagnostic,
+  deepEqual,
+  reconcileSharedIssueRecord,
+  readField,
+  writeField,
+};