codex-overleaf-link 2.2.0 → 2.3.0

package/extension/src/shared/writebackEvidenceProjection.js

@@ -0,0 +1,150 @@
+(function initCodexOverleafWritebackEvidenceProjection(root, factory) {
+  const api = factory();
+  if (typeof module === 'object' && module.exports) module.exports = api;
+  if (root) root.CodexOverleafWritebackEvidenceProjection = api;
+})(typeof window !== 'undefined' ? window : globalThis, function writebackEvidenceProjectionFactory() {
+  'use strict';
+
+  function aggregateFileSettlements(operationEvidence = [], readbacks = []) {
+    const byPath = new Map();
+    const byRelatedPath = new Map();
+    for (const evidence of operationEvidence) {
+      const key = evidence.path || evidence.targetPath || 'unknown file';
+      if (!byPath.has(key)) {
+        byPath.set(key, {
+          path: key,
+          operationIds: [],
+          relatedPaths: [],
+          applied: 'none',
+          documentEffect: 'unchanged',
+          readBack: 'unknown',
+          recoveryKind: '',
+          failureCodes: [],
+          operationCount: 0,
+          appliedCount: 0,
+          failedCount: 0
+        });
+      }
+      const file = byPath.get(key);
+      file.operationCount++;
+      file.operationIds.push(evidence.operationId);
+      if (evidence.targetPath && evidence.targetPath !== key && !file.relatedPaths.includes(evidence.targetPath)) {
+        file.relatedPaths.push(evidence.targetPath);
+        byRelatedPath.set(evidence.targetPath, file);
+      }
+      if (evidence.collection === 'applied' && evidence.ok !== false) file.appliedCount++;
+      if (evidence.collection !== 'applied' || evidence.ok === false) file.failedCount++;
+      if (evidence.changedDocument) file.documentEffect = 'changed';
+      else if (evidence.mayHaveMutated && file.documentEffect !== 'changed') file.documentEffect = 'possible';
+      for (const code of evidence.failureCodes) {
+        if (!file.failureCodes.includes(code)) file.failureCodes.push(code);
+      }
+    }
+    for (const readback of normalizeFileReadbackEvidence(readbacks)) {
+      const file = byPath.get(readback.path) || byRelatedPath.get(readback.path);
+      if (!file) continue;
+      const deletesPath = operationEvidence.some(evidence =>
+        evidence.kind === 'delete' && evidence.path === readback.path
+      );
+      file.readBack = deletesPath && readback.state === 'missing' ? 'match' : readback.state;
+      if (file.readBack === 'mismatch') {
+        file.documentEffect = file.documentEffect === 'unchanged' ? 'possible' : file.documentEffect;
+        if (!file.failureCodes.includes('write_observed_mismatch')) {
+          file.failureCodes.push('write_observed_mismatch');
+        }
+      }
+    }
+    return Array.from(byPath.values()).map(file => {
+      file.applied = file.appliedCount === file.operationCount
+        ? 'complete'
+        : file.appliedCount > 0
+          ? 'partial'
+          : file.failedCount > 0
+            ? 'failed'
+            : 'none';
+      delete file.operationCount;
+      delete file.appliedCount;
+      delete file.failedCount;
+      return file;
+    }).sort((left, right) => left.path.localeCompare(right.path));
+  }
+
+  function normalizeFileReadbackEvidence(value = []) {
+    return (Array.isArray(value) ? value : [])
+      .filter(item => item && typeof item.path === 'string')
+      .map(item => ({
+        path: item.path,
+        state: ['match', 'mismatch', 'missing', 'unknown'].includes(item.state)
+          ? item.state
+          : 'unknown'
+      }));
+  }
+
+  function deriveApplyResultReadbacks(applyResult = {}) {
+    const readbacksByPath = new Map();
+    const record = (path, state) => {
+      if (typeof path !== 'string' || !path) return;
+      const current = readbacksByPath.get(path);
+      if (current === 'mismatch') return;
+      if (state === 'mismatch' || !current) readbacksByPath.set(path, state);
+    };
+    for (const entry of [
+      ...(Array.isArray(applyResult?.applied) ? applyResult.applied : []),
+      ...(Array.isArray(applyResult?.skipped) ? applyResult.skipped : [])
+    ]) {
+      const operation = entry?.operation || {};
+      const result = entry?.result || {};
+      const code = result?.failure?.code || result?.code || '';
+      const path = operation.type === 'rename' || operation.type === 'move'
+        ? operation.to || operation.path
+        : operation.path;
+      if (code === 'write_observed_mismatch') {
+        record(path, 'mismatch');
+      } else if (result.verified === true) {
+        record(path, operation.type === 'delete' ? 'missing' : 'match');
+      }
+    }
+    return Array.from(readbacksByPath, ([path, state]) => ({ path, state }));
+  }
+
+  function deriveDocumentEffect(operationEvidence = []) {
+    if (operationEvidence.some(entry => entry.changedDocument === true)) return 'changed';
+    if (operationEvidence.some(entry => entry.mayHaveMutated === true)) return 'possibly-changed';
+    if (operationEvidence.length) return 'unchanged';
+    return 'unknown';
+  }
+
+  function deriveAppliedEvidence(operations = [], operationEvidence = []) {
+    const plannedCount = Array.isArray(operations) ? operations.length : 0;
+    const applied = operationEvidence.filter(entry => entry.collection === 'applied');
+    const skipped = operationEvidence.filter(entry => entry.collection === 'skipped');
+    const successful = applied.filter(entry => entry.ok !== false);
+    if (!plannedCount && !operationEvidence.length) return 'none';
+    if (!successful.length && (skipped.length || applied.some(entry => entry.ok === false))) return 'none';
+    if (successful.length && (skipped.length || applied.some(entry => entry.ok === false))) return 'partial';
+    if (successful.length && (!plannedCount || successful.length >= plannedCount)) return 'complete';
+    return successful.length ? 'partial' : 'unknown';
+  }
+
+  function deriveReadbackEvidence(fileSettlements = [], readbacks = []) {
+    if (!Array.isArray(readbacks) || !readbacks.length) return 'not-attempted';
+    const states = fileSettlements.map(file => file.readBack);
+    if (states.includes('mismatch')) return 'mismatch';
+    const exactCount = states.filter(state => state === 'match').length;
+    const unavailableCount = states.filter(state =>
+      state === 'missing' || state === 'unknown'
+    ).length;
+    if (exactCount && unavailableCount) return 'partial';
+    if (exactCount && exactCount === states.length) return 'exact';
+    return 'unavailable';
+  }
+
+  return Object.freeze({
+    aggregateFileSettlements,
+    deriveAppliedEvidence,
+    deriveApplyResultReadbacks,
+    deriveDocumentEffect,
+    deriveReadbackEvidence,
+    normalizeFileReadbackEvidence
+  });
+});

package/extension/src/shared/writebackOperationEvidence.js

@@ -0,0 +1,143 @@
+(function initCodexOverleafWritebackOperationEvidence(root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory();
+  } else {
+    root.CodexOverleafModuleRegistry.define('WritebackOperationEvidence', [], factory);
+  }
+})(typeof window !== 'undefined' ? window : globalThis, function writebackOperationEvidenceFactory() {
+  'use strict';
+
+  function normalizeOperationEvidence(operations = [], applyResult = {}) {
+    const planned = Array.isArray(operations) ? operations : [];
+    const entries = [];
+    const claimedPlanned = new Set();
+    let fallbackCursor = 0;
+
+    const operationKey = operation => {
+      if (!operation || typeof operation !== 'object') return '';
+      return normalizeText(operation.id)
+        || [
+          normalizeText(operation.type),
+          normalizeText(operation.path || operation.from),
+          normalizeText(operation.to || operation.destinationPath),
+          Number.isFinite(Number(operation.sequence)) ? Number(operation.sequence) : ''
+        ].join(':');
+    };
+
+    const claimPlannedOperation = explicitOperation => {
+      if (explicitOperation && typeof explicitOperation === 'object') {
+        const explicitKey = operationKey(explicitOperation);
+        const matchedIndex = planned.findIndex((operation, plannedIndex) =>
+          !claimedPlanned.has(plannedIndex) && operationKey(operation) === explicitKey
+        );
+        if (matchedIndex >= 0) claimedPlanned.add(matchedIndex);
+        return explicitOperation;
+      }
+      while (claimedPlanned.has(fallbackCursor)) fallbackCursor++;
+      if (fallbackCursor >= planned.length) return {};
+      const operation = planned[fallbackCursor];
+      claimedPlanned.add(fallbackCursor);
+      fallbackCursor++;
+      return operation;
+    };
+
+    const push = (entry, collection, index) => {
+      const operation = claimPlannedOperation(entry?.operation);
+      const result = entry?.result || entry || {};
+      const failure = normalizeFailure(result, operation);
+      const changedDocument = result.changedDocument === true
+        || (collection === 'applied' && result.ok !== false);
+      const mayHaveMutated = changedDocument
+        || result.mayHaveMutated === true
+        || failure?.changedDocument === true;
+      entries.push({
+        operationId: normalizeText(operation.id) || `${collection}:${index}:${operation.type || 'unknown'}:${operation.path || operation.to || ''}`,
+        sequence: Number.isFinite(Number(operation.sequence)) ? Number(operation.sequence) : index,
+        path: normalizeText(operation.path || operation.from),
+        targetPath: normalizeText(operation.to || operation.destinationPath),
+        kind: normalizeText(operation.type) || 'unknown',
+        collection,
+        ok: result.ok !== false,
+        changedDocument,
+        mayHaveMutated,
+        failureCodes: failure?.code ? [failure.code] : [],
+        failures: failure ? [failure] : [],
+        trackedChanges: normalizeTrackedChanges(result.trackedChanges || entry?.trackedChanges),
+        undoIds: normalizeStringArray(result.undoIds || entry?.undoIds),
+        baseAvailable: operation.baseContent !== undefined || operation.expected !== undefined,
+        expectedAvailable: operation.expected !== undefined || result.verifiedContent !== undefined
+      });
+    };
+    (Array.isArray(applyResult?.applied) ? applyResult.applied : [])
+      .forEach((entry, index) => push(entry, 'applied', index));
+    (Array.isArray(applyResult?.skipped) ? applyResult.skipped : [])
+      .forEach((entry, index) => push(entry, 'skipped', index));
+    planned.forEach((operation, index) => {
+      if (claimedPlanned.has(index)) return;
+      const path = normalizeText(operation?.path || operation?.from || operation?.to);
+      push({
+        operation,
+        result: {
+          ok: false,
+          mayHaveMutated: false,
+          failure: {
+            code: 'write_result_missing',
+            stage: 'write',
+            severity: 'error',
+            userMessage: `No write result was returned for ${path || 'a planned operation'}.`,
+            retryable: true,
+            nextAction: 'Retry the task and review the Overleaf document before continuing.',
+            file: path,
+            operationType: normalizeText(operation?.type),
+            changedDocument: false,
+            terminalState: 'needs_review'
+          }
+        }
+      }, 'skipped', index);
+    });
+    return entries;
+  }
+
+  function normalizeFailure(result, operation) {
+    if (result?.failure && typeof result.failure === 'object') return cloneValue(result.failure);
+    if (!result?.code) return null;
+    return {
+      code: result.code,
+      stage: result.stage || 'write',
+      severity: result.severity || 'error',
+      userMessage: result.reason || result.message || result.code,
+      retryable: result.retryable === true,
+      file: operation?.path || operation?.to || '',
+      changedDocument: result.changedDocument === true,
+      terminalState: result.terminalState || ''
+    };
+  }
+
+  function normalizeTrackedChanges(value) {
+    return (Array.isArray(value) ? value : []).map(item => ({
+      key: normalizeText(item?.key),
+      id: normalizeText(item?.id),
+      path: normalizeText(item?.path),
+      label: normalizeText(item?.label)
+    })).filter(item => item.key || item.id || item.path);
+  }
+
+  function normalizeStringArray(value) {
+    return (Array.isArray(value) ? value : []).map(normalizeText).filter(Boolean);
+  }
+
+  function cloneValue(value) {
+    if (value === undefined) return undefined;
+    return JSON.parse(JSON.stringify(value));
+  }
+
+  function normalizeText(value) {
+    return typeof value === 'string' ? value.trim() : '';
+  }
+
+  return {
+    normalizeFailure,
+    normalizeOperationEvidence,
+    normalizeTrackedChanges
+  };
+});