forge-workflow 0.0.9 → 0.1.0-beta.2

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

package/lib/issue-sync/schema.js

@@ -0,0 +1,126 @@
+function createDefaultGitHubSection() {
+  return {
+    number: null,
+    nodeId: null,
+    url: null,
+  };
+}
+
+function createDefaultSharedSection() {
+  return {
+    title: '',
+    body: '',
+    state: 'open',
+    assignees: [],
+    labels: [],
+    milestone: null,
+  };
+}
+
+function createDefaultForgeSection() {
+  return {
+    issueId: null,
+    dependencies: [],
+    parentId: null,
+    childIds: [],
+    workflowStage: null,
+    acceptanceCriteria: [],
+    progressNotes: [],
+    stageTransitions: [],
+    decisions: [],
+    memory: [],
+  };
+}
+
+function createDefaultCacheSection() {
+  return {
+    githubSnapshot: null,
+    materializedIssue: null,
+    legacyLinkHints: {
+      mapping: null,
+      githubIssue: null,
+      syncComments: [],
+      externalRef: null,
+      descriptionUrl: null,
+    },
+  };
+}
+
+function createDefaultSyncSection() {
+  return {
+    remoteUpdatedAt: null,
+    lastPulledAt: null,
+    lastPushedAt: null,
+    pendingOutbound: [],
+    drift: [],
+  };
+}
+
+function createDefaultSharedIssueRecord() {
+  return {
+    github: createDefaultGitHubSection(),
+    shared: createDefaultSharedSection(),
+    forge: createDefaultForgeSection(),
+    cache: createDefaultCacheSection(),
+    sync: createDefaultSyncSection(),
+  };
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function cloneValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(cloneValue);
+  }
+
+  if (isPlainObject(value)) {
+    const result = {};
+
+    for (const [key, nestedValue] of Object.entries(value)) {
+      result[key] = cloneValue(nestedValue);
+    }
+
+    return result;
+  }
+
+  return value;
+}
+
+function mergeRecordSections(baseValue, overrideValue) {
+  if (overrideValue === undefined) {
+    return cloneValue(baseValue);
+  }
+
+  if (Array.isArray(overrideValue)) {
+    return overrideValue.map(cloneValue);
+  }
+
+  if (!isPlainObject(baseValue) || !isPlainObject(overrideValue)) {
+    return cloneValue(overrideValue);
+  }
+
+  const merged = {};
+  const keys = new Set([...Object.keys(baseValue), ...Object.keys(overrideValue)]);
+
+  for (const key of keys) {
+    merged[key] = mergeRecordSections(baseValue[key], overrideValue[key]);
+  }
+
+  return merged;
+}
+
+function buildSharedIssueRecord(overrides = {}) {
+  return mergeRecordSections(createDefaultSharedIssueRecord(), overrides);
+}
+
+module.exports = {
+  buildSharedIssueRecord,
+  createDefaultCacheSection,
+  createDefaultForgeSection,
+  createDefaultGitHubSection,
+  createDefaultSharedIssueRecord,
+  createDefaultSharedSection,
+  createDefaultSyncSection,
+};