refactor(git-sync): internalize the engine — first-class ESM, no vendoring bridge (#119 review)

Closes the architecture item from the #119 review: drop the "vendored from
docmost-sync" framing and the CJS↔ESM `Function('import()')` bridge so the engine
is a normal first-class gitmost package.

Part 1 — vendoring markers removed (prose only, zero behavior change): reworded
"VENDORED into gitmost" / "vendored from docmost-sync" / "Engine LOGIC is
byte-identical" / "it's a port" comments across the engine. Behavior-bearing
strings are untouched: BOT_AUTHOR_NAME/EMAIL and the `Docmost-Sync-Source:`
provenance trailers (changing them would break git authorship + the loop-guard).

Part 2 — the package is now ESM (matching the sibling @docmost/mcp): `type: module`,
tsconfig Node16, `.js` extensions on relative imports, and a static
`import { marked }` replacing the `new Function('return import(...)')` /
`loadMarked` hack — the bridge is GONE from the package. The CommonJS NestJS
server loads the now-ESM engine via a new `git-sync.loader.ts` that mirrors the
existing `docmost-client.loader.ts` mcp loader exactly (Function-indirected
dynamic import + cached promise + retry-on-reject). The 4 server consumers
(orchestrator/datasource/vault-registry/git-http-backend) call `await loadGitSync()`
for value exports; types stay `import type` (erased). The converter-gate spec —
which needs the real converter — loads the package's TS source via a jest
moduleNameMapper + isolatedModules (documented in that spec); the other git-sync
specs mock the loader.

Verified: engine builds pure ESM (no Function/require leftover), vitest 614,
editor-ext build, server + client tsc, full server jest 1397/0. Live stand
smoke-test: server starts clean on the ESM engine (no ERR_REQUIRE_ESM), a real
sync cycle runs through the loader, and the basic e2e suite is 12/12 (clone via
git-http-backend, push, pull, delete, 3-way merge — all through the new loader).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
claude code agent 227
2026-06-24 14:23:40 +03:00
parent 3a91e0eca9
commit 5da12e89f9
29 changed files with 270 additions and 205 deletions
@@ -1,17 +1,30 @@
// Unit tests for the per-space vault path resolver + lazy VaultGit cache
// `mkdir` and `VaultGit` are mocked so construction is cheap and
// `mkdir` and the git-sync loader are mocked so construction is cheap and
// no real filesystem / git work happens. We assert the path normalization
// (trailing slash) and the one-VaultGit-per-space caching contract.
//
// The service loads `VaultGit` (and `vaultGitEnv`) at runtime via the
// `loadGitSync()` bridge (the ESM `@docmost/git-sync` package cannot be
// `require()`d under jest), so we mock that loader rather than the package.
import { mkdir } from 'node:fs/promises';
import { VaultGit } from '@docmost/git-sync';
import { loadGitSync } from '../git-sync.loader';
jest.mock('node:fs/promises', () => ({
mkdir: jest.fn(async () => undefined),
}));
// Cheap VaultGit stub: records the path it was constructed with; no shell-out.
jest.mock('@docmost/git-sync', () => ({
VaultGit: jest.fn().mockImplementation((path: string) => ({ path })),
// Declared with a `mock`-prefixed name so jest allows referencing it inside the
// hoisted `jest.mock` factory below.
const mockVaultGit = jest
.fn()
.mockImplementation((path: string) => ({ path }));
jest.mock('../git-sync.loader', () => ({
loadGitSync: jest.fn(async () => ({
VaultGit: mockVaultGit,
vaultGitEnv: jest.fn(() => ({})),
})),
}));
import { VaultRegistryService } from './vault-registry.service';
@@ -19,7 +32,8 @@ import { VaultRegistryService } from './vault-registry.service';
type AnyMock = jest.Mock;
const mkdirMock = mkdir as unknown as AnyMock;
const VaultGitMock = VaultGit as unknown as AnyMock;
const VaultGitMock = mockVaultGit;
void loadGitSync;
function build(dataDir: string): { service: VaultRegistryService } {
const env = {