docmost-sync/test/run-push.test.ts

import { describe, expect, it, vi } from 'vitest';
import { runPush, LAST_PUSHED_REF, DOCMOST_BRANCH } from '../src/push.js';
import type { PushDeps } from '../src/push.js';
import type { Settings } from '../src/settings.js';
import { serializeDocmostMarkdownBody } from '../packages/docmost-client/src/lib/markdown-document.js';

// runPush orchestration (SPEC §6 "ФС → Docmost"), DRY-RUN BY DEFAULT. Driven by
// FAKES only — no live Docmost, git, fs, or network. Asserts the SAFE-BY-DEFAULT
// contract: a dry-run builds NO client, makes ZERO Docmost calls, advances NO
// refs; `--apply` is the ONLY path that writes. Also covers the merge-in-progress
// abort, the divergent-`docmost` escalation, and the base selection fallback.

/** A minimal valid Settings fixture (only fields runPush reads matter). */
function makeSettings(): Settings {
  return {
    docmostApiUrl: 'https://docmost.example.com',
    docmostEmail: 'you@example.com',
    docmostPassword: 'secret',
    docmostSpaceId: 'space-1',
    vaultPath: '/vault',
    pollIntervalMs: 15000,
    debounceMs: 2000,
    logLevel: 'info',
  };
}

/**
 * A recording git fake covering exactly the `PushDeps['git']` surface. Options
 * configure the diff rows, which refs resolve, and what the ff returns.
 */
function makeGit(opts?: {
  mergeInProgress?: boolean;
  lastPushed?: string | null;
  docmostSha?: string | null;
  mainSha?: string;
  /** Diff rows returned by diffNameStatus(base, main). */
  changes?: { status: 'A' | 'M' | 'D' | 'R' | 'C'; path: string; oldPath?: string }[];
  /** Pre-image tree at the base ref (path -> text) for showFileAtRef. */
  prevTree?: Record<string, string>;
  ffResult?: { ok: boolean; reason?: string };
  /** When set, commit returns this per call (queue); defaults to always-true. */
  commitResults?: boolean[];
}) {
  const calls = {
    assertGitAvailable: 0,
    ensureRepo: 0,
    checkout: [] as string[],
    stageAll: 0,
    commit: [] as string[],
    updateRef: [] as { ref: string; target: string }[],
    fastForwardBranch: [] as { branch: string; toCommit: string }[],
    diffNameStatus: [] as { from: string; to: string }[],
  };
  const prevTree = opts?.prevTree ?? {};
  const commitQueue = [...(opts?.commitResults ?? [])];
  let mainSha = opts?.mainSha ?? 'main-sha-1';

  const git: PushDeps['git'] = {
    assertGitAvailable: vi.fn(async () => {
      calls.assertGitAvailable++;
    }),
    ensureRepo: vi.fn(async () => {
      calls.ensureRepo++;
    }),
    isMergeInProgress: vi.fn(async () => opts?.mergeInProgress ?? false),
    checkout: vi.fn(async (name: string) => {
      calls.checkout.push(name);
    }),
    stageAll: vi.fn(async () => {
      calls.stageAll++;
    }),
    commit: vi.fn(async (subject: string) => {
      calls.commit.push(subject);
      return commitQueue.length > 0 ? (commitQueue.shift() as boolean) : true;
    }),
    readRef: vi.fn(async (ref: string) =>
      ref === LAST_PUSHED_REF ? (opts?.lastPushed ?? null) : null,
    ),
    revParse: vi.fn(async (ref: string) => {
      if (ref === DOCMOST_BRANCH) return opts?.docmostSha ?? null;
      if (ref === 'main') return mainSha;
      return null;
    }),
    diffNameStatus: vi.fn(async (from: string, to: string) => {
      calls.diffNameStatus.push({ from, to });
      return opts?.changes ?? [];
    }),
    showFileAtRef: vi.fn(async (_ref: string, path: string) =>
      path in prevTree ? prevTree[path] : null,
    ),
    updateRef: vi.fn(async (ref: string, target: string) => {
      calls.updateRef.push({ ref, target });
    }),
    fastForwardBranch: vi.fn(async (branch: string, toCommit: string) => {
      calls.fastForwardBranch.push({ branch, toCommit });
      return opts?.ffResult ?? { ok: true };
    }),
  };
  return {
    git,
    calls,
    /** Advance the fake `main` HEAD (so a write-back commit yields a new sha). */
    setMainSha: (sha: string) => {
      mainSha = sha;
    },
  };
}

/** A recording client fake; createPage returns a configurable assigned id. */
function makeClientFake(opts?: { createId?: string }) {
  return {
    importPageMarkdown: vi.fn(async () => ({ success: true })),
    createPage: vi.fn(async (title: string) => ({
      data: { id: opts?.createId ?? 'assigned-id', title },
      success: true,
    })),
    deletePage: vi.fn(async () => ({ success: true })),
    movePage: vi.fn(async () => ({ success: true })),
    renamePage: vi.fn(async () => ({ success: true })),
  };
}

/** A recording fs fake over a path->text store. */
function makeFs(initial: Record<string, string> = {}) {
  const store: Record<string, string> = { ...initial };
  const reads: string[] = [];
  const writes: { path: string; text: string }[] = [];
  return {
    store,
    reads,
    writes,
    readFile: vi.fn(async (path: string) => {
      reads.push(path);
      if (!(path in store)) throw new Error(`no such file: ${path}`);
      return store[path];
    }),
    writeFile: vi.fn(async (path: string, text: string) => {
      store[path] = text;
      writes.push({ path, text });
    }),
  };
}

/** Assemble PushDeps with a recording logger and a makeClient FACTORY spy. */
function makeDeps(
  git: PushDeps['git'],
  fs: ReturnType<typeof makeFs>,
  client?: ReturnType<typeof makeClientFake>,
) {
  const logs: string[] = [];
  const makeClient = vi.fn(() => (client ?? makeClientFake()) as any);
  const deps: PushDeps = {
    settings: makeSettings(),
    git,
    makeClient,
    readFile: fs.readFile,
    writeFile: fs.writeFile,
    log: (line) => logs.push(line),
  };
  return { deps, logs, makeClient };
}

describe('runPush — dry-run is the DEFAULT (safe)', () => {
  it('logs a plan, builds NO client, makes ZERO Docmost calls, advances NO refs', async () => {
    const file =
      '<!-- docmost:meta\n{"version":1,"pageId":"p-1"}\n-->\n\nedited body\n';
    const { git, calls } = makeGit({
      lastPushed: 'base-sha',
      changes: [{ status: 'M', path: 'Doc.md' }],
    });
    const fs = makeFs({ 'Doc.md': file });
    const { deps, logs, makeClient } = makeDeps(git, fs);

    const res = await runPush(deps, { dryRun: true });

    expect(res.mode).toBe('dry-run');
    expect(res.planned).toEqual({
      creates: 0,
      updates: 1,
      deletes: 0,
      renamesMoves: 0,
      skipped: 0,
    });
    // The client FACTORY was never invoked -> zero Docmost contact.
    expect(makeClient).not.toHaveBeenCalled();
    // No ref advance, no mirror ff.
    expect(calls.updateRef).toEqual([]);
    expect(calls.fastForwardBranch).toEqual([]);
    // A plan WAS logged (counts + the per-item update line).
    expect(logs.join('\n')).toMatch(/DRY-RUN/);
    expect(logs.join('\n')).toMatch(/update: p-1 \(Doc\.md\)/);
    // It still diffs the base against main and works on main.
    expect(calls.diffNameStatus).toEqual([{ from: LAST_PUSHED_REF, to: 'main' }]);
    expect(calls.checkout).toEqual(['main']);
  });

  it('commits the working tree with the local provenance trailer before diffing', async () => {
    const { git, calls } = makeGit({ lastPushed: 'base-sha' });
    const fs = makeFs();
    const { deps } = makeDeps(git, fs);

    await runPush(deps, { dryRun: true });

    // The first commit is the human working-tree commit on main (SPEC §7.3).
    expect(calls.commit[0]).toBe('local: working-tree changes');
    expect(calls.stageAll).toBeGreaterThanOrEqual(1);
    const trailerArg = (git.commit as any).mock.calls[0][1];
    expect(trailerArg.trailers).toEqual(['Docmost-Sync-Source: local']);
  });
});

describe('runPush — --apply is the ONLY write path', () => {
  it('builds the client, calls applyPushActions, records created pageIds, advances last-pushed', async () => {
    // A brand-new local file: meta has title + spaceId but NO pageId yet.
    const newFile = serializeDocmostMarkdownBody(
      { version: 1, title: 'New', spaceId: 'sp-1' },
      'fresh body',
    );
    const { git, calls, setMainSha } = makeGit({
      lastPushed: 'base-sha',
      mainSha: 'main-1',
      changes: [{ status: 'A', path: 'New.md' }],
    });
    const fs = makeFs({ 'New.md': newFile });
    const client = makeClientFake({ createId: 'page-new' });
    const { deps, makeClient } = makeDeps(git, fs, client);
    // After the write-back commit, `main` moves to a new commit.
    (git.commit as any).mockImplementation(async (subject: string) => {
      calls.commit.push(subject);
      if (subject === 'local: record created pageIds') setMainSha('main-2');
      return true;
    });

    const res = await runPush(deps, { dryRun: false });

    expect(res.mode).toBe('apply');
    // The client factory WAS used and createPage ran (the write path).
    expect(makeClient).toHaveBeenCalledTimes(1);
    expect(client.createPage).toHaveBeenCalledTimes(1);
    expect(res.applied?.created).toBe(1);
    // The assigned pageId was written back into the file on disk.
    expect(res.applied?.writtenBack).toEqual([{ path: 'New.md', pageId: 'page-new' }]);
    expect(fs.store['New.md']).toMatch(/page-new/);
    // A "record created pageIds" commit persisted the write-back.
    expect(calls.commit).toContain('local: record created pageIds');
    // last-pushed was advanced — first by the applier (main-1), then re-advanced
    // to the write-back commit (main-2).
    const lastPushedAdvances = calls.updateRef.filter(
      (u) => u.ref === LAST_PUSHED_REF,
    );
    expect(lastPushedAdvances.map((u) => u.target)).toEqual(['main-1', 'main-2']);
    expect(res.divergentDocmost).toBe(false);
    expect(res.failures).toEqual([]);
  });

  it('ESCALATES a divergent docmost mirror in the write-back branch too (SPEC §5, symmetric)', async () => {
    // A create -> the pageId is written back and a "record created pageIds"
    // commit is made, which triggers the write-back-branch ff. Here the applier's
    // MAIN push ff succeeds (ok) but the WRITE-BACK ff diverges — the write-back
    // branch must escalate identically to the main branch (set divergentDocmost,
    // log the same prominent WARNING), so main() exits 1.
    const newFile = serializeDocmostMarkdownBody(
      { version: 1, title: 'New', spaceId: 'sp-1' },
      'fresh body',
    );
    const { git, calls, setMainSha } = makeGit({
      lastPushed: 'base-sha',
      mainSha: 'main-1',
      changes: [{ status: 'A', path: 'New.md' }],
    });
    const fs = makeFs({ 'New.md': newFile });
    const client = makeClientFake({ createId: 'page-new' });
    const { deps, logs } = makeDeps(git, fs, client);
    (git.commit as any).mockImplementation(async (subject: string) => {
      calls.commit.push(subject);
      if (subject === 'local: record created pageIds') setMainSha('main-2');
      return true;
    });
    // First ff (applier 7b, main push) is OK; second ff (write-back) DIVERGES.
    let ffCall = 0;
    (git.fastForwardBranch as any).mockImplementation(
      async (branch: string, toCommit: string) => {
        calls.fastForwardBranch.push({ branch, toCommit });
        ffCall++;
        return ffCall === 1
          ? { ok: true }
          : { ok: false, reason: 'not-fast-forward' };
      },
    );

    const res = await runPush(deps, { dryRun: false });

    // The apply still happened, but the write-back divergence is escalated.
    expect(res.applied?.created).toBe(1);
    expect(res.divergentDocmost).toBe(true);
    // The SAME prominent WARNING (DIVERGED + §5) — not a soft warning.
    expect(logs.join('\n')).toMatch(/WARNING/);
    expect(logs.join('\n')).toMatch(/DIVERGED/);
    expect(logs.join('\n')).toMatch(/write-back/);
  });

  it('an update goes through importPageMarkdown (collab path)', async () => {
    const file =
      '<!-- docmost:meta\n{"version":1,"pageId":"p-9"}\n-->\n\nbody\n';
    const { git } = makeGit({
      lastPushed: 'base-sha',
      changes: [{ status: 'M', path: 'Doc.md' }],
    });
    const fs = makeFs({ 'Doc.md': file });
    const client = makeClientFake();
    const { deps } = makeDeps(git, fs, client);

    const res = await runPush(deps, { dryRun: false });

    expect(client.importPageMarkdown).toHaveBeenCalledWith('p-9', file);
    expect(res.applied?.updated).toBe(1);
  });
});

describe('runPush — merge-in-progress aborts (SPEC §9/§12)', () => {
  it('stops with a clear message, no diff, no client, no apply', async () => {
    const { git, calls } = makeGit({ mergeInProgress: true });
    const fs = makeFs();
    const { deps, logs, makeClient } = makeDeps(git, fs);

    const res = await runPush(deps, { dryRun: false });

    expect(res.aborted).toBe('merge-in-progress');
    // Never diffed, never built a client, never checked out / committed.
    expect(calls.diffNameStatus).toEqual([]);
    expect(makeClient).not.toHaveBeenCalled();
    expect(calls.checkout).toEqual([]);
    expect(logs.join('\n')).toMatch(/unresolved merge/);
    expect(logs.join('\n')).toMatch(/SPEC §9/);
  });
});

describe('runPush — divergent docmost escalation (SPEC §5)', () => {
  it('sets the escalation flag and logs a WARNING, but the apply still happened', async () => {
    const file =
      '<!-- docmost:meta\n{"version":1,"pageId":"p-1"}\n-->\n\nbody\n';
    const { git } = makeGit({
      lastPushed: 'base-sha',
      changes: [{ status: 'M', path: 'Doc.md' }],
      // The applier refuses to clobber a divergent mirror.
      ffResult: { ok: false, reason: 'not-fast-forward' },
    });
    const fs = makeFs({ 'Doc.md': file });
    const client = makeClientFake();
    const { deps, logs } = makeDeps(git, fs, client);

    const res = await runPush(deps, { dryRun: false });

    // The apply STILL happened (the page was updated)...
    expect(res.applied?.updated).toBe(1);
    expect(client.importPageMarkdown).toHaveBeenCalledTimes(1);
    // ...but the divergence is escalated, not silent.
    expect(res.divergentDocmost).toBe(true);
    expect(logs.join('\n')).toMatch(/WARNING/);
    expect(logs.join('\n')).toMatch(/DIVERGED/);
  });
});

describe('runPush — base selection (last-pushed else docmost)', () => {
  it('uses refs/docmost/last-pushed when it resolves', async () => {
    const { git, calls } = makeGit({ lastPushed: 'lp-sha' });
    const fs = makeFs();
    const { deps } = makeDeps(git, fs);

    const res = await runPush(deps, { dryRun: true });

    expect(res.base).toEqual({
      ref: LAST_PUSHED_REF,
      source: 'last-pushed',
      sha: 'lp-sha',
    });
    expect(calls.diffNameStatus[0].from).toBe(LAST_PUSHED_REF);
  });

  it('falls back to the docmost branch when last-pushed is missing', async () => {
    const { git, calls } = makeGit({
      lastPushed: null, // last-pushed does not resolve -> fall back.
      docmostSha: 'doc-sha',
    });
    const fs = makeFs();
    const { deps } = makeDeps(git, fs);

    const res = await runPush(deps, { dryRun: true });

    expect(res.base).toEqual({
      ref: DOCMOST_BRANCH,
      source: 'docmost',
      sha: 'doc-sha',
    });
    // The diff is taken against the docmost mirror branch.
    expect(calls.diffNameStatus[0].from).toBe(DOCMOST_BRANCH);
  });
});