@codeyam-editor/codeyam-editor 0.1.4 → 0.1.6

package/npm/script-drift.js

@@ -0,0 +1,152 @@
+'use strict';
+
+/**
+ * Given a list of files with their hash values, decide if there is any script drift.
+ * @param {Object} options
+ * @param {Array<Object>} options.files
+ * Each file entry has:
+ *  {
+ *    path: string,
+ *    localHash: string,
+ *    remoteHash: string | null, // null indicates fetch/hash failure
+ *    baseHash: string | null,
+ *    dirty: boolean
+ *  }
+ * 
+ * Returns:
+ *  {
+ *    verdict: 'clean' | 'local-ahead' | 'stale' | 'diverged',
+ *    staleFiles: string[] // List of paths that are stale/diverged
+ *  }
+ */
+function classifyScriptDrift({ files }) {
+  if (!files || files.length === 0) {
+    return { verdict: 'clean', staleFiles: [] };
+  }
+
+  let hasStale = false;
+  let hasDiverged = false;
+  let hasLocalAhead = false;
+  const staleFiles = [];
+
+  for (const f of files) {
+    // If remoteHash or baseHash is missing/null/undefined, we treat it as fetch/hash failure.
+    // In that case, we cannot safely declare the file stale/diverged, so we pass through.
+    if (f.remoteHash === null || f.baseHash === null || f.remoteHash === undefined || f.baseHash === undefined) {
+      continue;
+    }
+
+    const localHash = f.localHash;
+    const remoteHash = f.remoteHash;
+    const baseHash = f.baseHash;
+    const dirty = !!f.dirty;
+
+    // 1. Identical local and remote, and not dirty locally -> clean
+    if (localHash === remoteHash && !dirty) {
+      continue;
+    }
+
+    // 2. Remote hasn't changed from base, but local has changed (or is dirty)
+    if (remoteHash === baseHash) {
+      if (localHash !== baseHash || dirty) {
+        hasLocalAhead = true;
+      }
+    } 
+    // 3. Local hasn't changed from base, but remote has changed from base
+    else if (localHash === baseHash && !dirty) {
+      hasStale = true;
+      staleFiles.push(f.path);
+    } 
+    // 4. Both local and remote have changed from base and they differ from each other
+    else {
+      hasDiverged = true;
+      staleFiles.push(f.path);
+    }
+  }
+
+  if (hasDiverged) {
+    return { verdict: 'diverged', staleFiles };
+  }
+  if (hasStale) {
+    return { verdict: 'stale', staleFiles };
+  }
+  if (hasLocalAhead) {
+    return { verdict: 'local-ahead', staleFiles: [] };
+  }
+  return { verdict: 'clean', staleFiles: [] };
+}
+
+/**
+ * Decide, for one streamed provisioning script, whether the VM should receive the
+ * canonical remote-tip bytes or the local on-disk copy. The remote tip is the
+ * reviewed, canonical source: a checkout that is merely *behind* origin (a normal,
+ * expected consequence of an active fleet landing commits to these scripts) then
+ * streams exactly the bytes the drift guard expects — never stale on-disk bytes,
+ * never a false STALE abort. The local copy wins only when the operator authored
+ * content the remote tip does not have — an uncommitted (dirty) edit or a committed
+ * local-ahead change (developer mode / diverged) — or when the remote facts are
+ * unavailable (offline fallback, so an offline operator can still provision).
+ *
+ * @param {Object} file
+ * @param {string|null} file.localHash
+ * @param {string|null} file.remoteHash  null/undefined ⇒ remote unreachable
+ * @param {string|null} file.baseHash
+ * @param {boolean} file.dirty
+ * @returns {'remote' | 'local'}
+ */
+function streamedScriptSource({ localHash, remoteHash, baseHash, dirty }) {
+  // Remote unreachable / ref missing → the only bytes we have are on disk.
+  if (remoteHash === null || remoteHash === undefined) {
+    return 'local';
+  }
+  // Uncommitted local edit → the operator is provisioning unreviewed bytes on
+  // purpose (developer mode, or an explicit CODEYAM_SKIP_SCRIPT_DRIFT_CHECK bypass).
+  if (dirty) {
+    return 'local';
+  }
+  // Local content the remote tip does not have (committed local-ahead, or a genuine
+  // divergence): local differs from the remote tip AND from the merge base → honor
+  // the local commit rather than silently overwriting it with the remote tip.
+  if (localHash !== remoteHash && localHash !== baseHash) {
+    return 'local';
+  }
+  // Clean, or merely behind the remote tip → stream the canonical remote-tip bytes.
+  return 'remote';
+}
+
+/**
+ * Decide what the streamed-script drift preflight should do, from the classifier
+ * verdict plus which streamed files carry uncommitted edits. A checkout that is
+ * merely *behind* origin (verdict 'stale') is benign — the add streams the
+ * canonical remote-tip bytes (see streamedScriptSource), so it never blocks. The
+ * guard fires ('block') only for local content the remote tip does not have: an
+ * uncommitted (dirty) edit, or a genuine divergence. A committed local-ahead
+ * change is developer mode — warn, don't block.
+ *
+ * @param {Object} o
+ * @param {string} o.verdict      classifyScriptDrift verdict
+ * @param {string[]} [o.staleFiles] files the classifier flagged (the diverged set)
+ * @param {string[]} [o.dirtyFiles] streamed files with uncommitted local edits
+ * @returns {{ block: boolean, reason: 'clean'|'behind'|'local-ahead'|'dirty'|'diverged', blockedFiles: string[] }}
+ */
+function scriptDriftGuardAction({ verdict, staleFiles = [], dirtyFiles = [] }) {
+  if (verdict === 'diverged') {
+    return { block: true, reason: 'diverged', blockedFiles: staleFiles };
+  }
+  if (dirtyFiles.length > 0) {
+    return { block: true, reason: 'dirty', blockedFiles: dirtyFiles };
+  }
+  if (verdict === 'stale') {
+    return { block: false, reason: 'behind', blockedFiles: [] };
+  }
+  if (verdict === 'local-ahead') {
+    return { block: false, reason: 'local-ahead', blockedFiles: [] };
+  }
+  return { block: false, reason: 'clean', blockedFiles: [] };
+}
+
+module.exports = {
+  classifyScriptDrift,
+  streamedScriptSource,
+  scriptDriftGuardAction
+};