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 5ca4cc4657
commit c76f255b1c
29 changed files with 270 additions and 205 deletions

View File

@@ -1,7 +1,17 @@
/**
* JEST CONFIG NOTE (#119 ESM refactor): this is the one spec that needs the REAL
* `@docmost/git-sync` converter (not a mock). The package is now ESM, which jest
* cannot `require()` nor `import()` without --experimental-vm-modules, so the
* server jest config `moduleNameMapper`s `@docmost/git-sync` to its TS SOURCE and
* strips the ESM `.js` import suffixes. ts-jest then type-checks that source under
* the server's (looser) tsconfig and trips a benign narrowing; the global
* `isolatedModules: true` on the ts-jest transform (apps/server/package.json)
* makes it transpile-only so this spec loads. Full type-checking of the package
* is still enforced by its own `tsc`/vitest gates and the server `tsc --noEmit`.
*
* §13.1 IDEMPOTENCY GATE — the blocking gate for git-sync Phase B.
*
* Proves the vendored `@docmost/git-sync` pure converter is schema-compatible
* Proves the `@docmost/git-sync` pure converter is schema-compatible
* with the server's REAL editor-ext document schema: a representative corpus of
* editor-ext ProseMirror documents must survive a full round trip through the
* actual server write path without losing any node / mark / attribute.
@@ -19,7 +29,7 @@
* validation that runs on a git-sync write (plan §3.3).
* 4. assert docsCanonicallyEqual(canon(original), canon(normalized)) === true
*
* Any node / mark / attr that editor-ext drops (because the vendored
* Any node / mark / attr that editor-ext drops (because the git-sync
* docmost-schema named it differently, or declares a different default) makes
* the gate FAIL for that document — exactly the schema-divergence plan §3.3 /
* §13.1 warn about. Genuine, irreducible divergences are isolated into the
@@ -31,9 +41,11 @@
*/
import { TiptapTransformer } from '@hocuspocus/transformer';
// Import the server's real schema FIRST so `@docmost/editor-ext` resolves to its
// built CJS `dist` (its `main`). Importing the ESM `@docmost/git-sync` package
// first flips jest's resolver to editor-ext's `module` (src) field, which then
// drags in React node views (navigator-less) and breaks the node test env.
// built CJS `dist` (its `main`). The ESM-only `@docmost/git-sync` package is
// mapped to its TS SOURCE by the jest `moduleNameMapper` (the built ESM cannot
// be `require()`d nor dynamically `import()`ed under jest's node VM), so ts-jest
// transpiles the real converter to CJS here — exercising the actual converter
// the server ships, not a stub.
import { tiptapExtensions } from './collaboration.util';
import {
convertProseMirrorToMarkdown,