Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): eliminate EditorArea import-cycle CI flake at root (#1850)

Nick Gomezbfd7838c2b31
diff --git a/packages/app/src/App.tsx b/packages/app/src/App.tsx
index da4944523..eb373bc9f 100644
--- a/packages/app/src/App.tsx
+++ b/packages/app/src/App.tsx
@@ -1,5 +1,5 @@
import { mediaKindForSidebarAssetExtension, SHOW_INSTALL_SKILL } from '@inkeep/open-knowledge-core';
-import { useEffect, useRef, useState } from 'react';
+import { type ReactNode, useEffect, useRef, useState } from 'react';
import { CommandPalette } from '@/components/CommandPalette';
import { ConnectingBanner } from '@/components/ConnectingBanner';
import { CreateProjectMenuTrigger } from '@/components/CreateProjectMenuTrigger';
@@ -292,15 +292,20 @@ function NewItemShortcutHandler() {
);
}
+function ConfigProviderHost({ children }: { children: ReactNode }) {
+ const { collabUrl } = useDocumentContext();
+ return <ConfigProvider collabUrl={collabUrl}>{children}</ConfigProvider>;
+}
+
export function App() {
return (
<ProfilerBoundary name="app">
<DocumentProvider>
- <ConfigProvider>
+ <ConfigProviderHost>
<SingleFileModeProvider>
<AppBody />
</SingleFileModeProvider>
- </ConfigProvider>
+ </ConfigProviderHost>
</DocumentProvider>
</ProfilerBoundary>
);
diff --git a/packages/app/src/editor/no-runtime-import-cycle.test.ts b/packages/app/src/editor/no-runtime-import-cycle.test.ts
new file mode 100644
index 000000000..932e084c8
--- /dev/null
+++ b/packages/app/src/editor/no-runtime-import-cycle.test.ts
@@ -0,0 +1,180 @@
+import { describe, expect, test } from 'bun:test';
+import { dirname, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Project } from 'ts-morph';
+
+const HERE = dirname(fileURLToPath(import.meta.url)); // packages/app/src/editor
+const APP_SRC = dirname(HERE); // packages/app/src
+const APP_DIR = dirname(APP_SRC); // packages/app
+const LIB_DIR = join(APP_SRC, 'lib') + sep;
+const EDITOR_DIR = join(APP_SRC, 'editor') + sep;
+const DOCUMENT_CONTEXT = join(APP_SRC, 'editor', 'DocumentContext.tsx');
+const CONFIG_PROVIDER = join(APP_SRC, 'lib', 'config-provider.tsx');
+
+const isTestLike = (p: string) => /\.(test|test-helper)\.[cm]?tsx?$/.test(p) || p.endsWith('.d.ts');
+
+interface ValueEdge {
+ from: string;
+ to: string;
+ line: number;
+ spec: string;
+}
+
+const project = new Project({
+ tsConfigFilePath: join(APP_DIR, 'tsconfig.json'),
+ skipAddingFilesFromTsConfig: false,
+});
+
+const files = project.getSourceFiles().filter((sf) => {
+ const p = sf.getFilePath();
+ return p.startsWith(APP_SRC + sep) && !isTestLike(p);
+});
+const fileSet = new Set<string>(files.map((sf) => sf.getFilePath()));
+
+const adjacency = new Map<string, Set<string>>();
+const edges: ValueEdge[] = [];
+
+const linkOf = (from: string): Set<string> => {
+ let set = adjacency.get(from);
+ if (!set) {
+ set = new Set();
+ adjacency.set(from, set);
+ }
+ return set;
+};
+
+for (const sf of files) {
+ const from = sf.getFilePath();
+
+ for (const imp of sf.getImportDeclarations()) {
+ if (imp.isTypeOnly()) continue; // `import type { … }` — fully erased at runtime
+ const target = imp.getModuleSpecifierSourceFile();
+ if (!target) continue; // external dep or unresolved — not a node in our graph
+ const to = target.getFilePath();
+ if (to === from || !fileSet.has(to)) continue;
+ linkOf(from).add(to);
+ edges.push({ from, to, line: imp.getStartLineNumber(), spec: imp.getModuleSpecifierValue() });
+ }
+
+ for (const exp of sf.getExportDeclarations()) {
+ if (!exp.getModuleSpecifier() || exp.isTypeOnly()) continue;
+ const target = exp.getModuleSpecifierSourceFile();
+ if (!target) continue;
+ const to = target.getFilePath();
+ if (to === from || !fileSet.has(to)) continue;
+ linkOf(from).add(to);
+ edges.push({
+ from,
+ to,
+ line: exp.getStartLineNumber(),
+ spec: exp.getModuleSpecifierValue() ?? '',
+ });
+ }
+}
+
+const nodes = [...fileSet].sort();
+
+function computeSccGroups(): string[][] {
+ const groups: string[][] = [];
+ let counter = 0;
+ const index = new Map<string, number>();
+ const lowlink = new Map<string, number>();
+ const onStack = new Set<string>();
+ const stack: string[] = [];
+
+ const strongconnect = (v: string): void => {
+ index.set(v, counter);
+ lowlink.set(v, counter);
+ counter += 1;
+ stack.push(v);
+ onStack.add(v);
+
+ for (const w of [...(adjacency.get(v) ?? [])].sort()) {
+ if (!index.has(w)) {
+ strongconnect(w);
+ lowlink.set(v, Math.min(lowlink.get(v) ?? 0, lowlink.get(w) ?? 0));
+ } else if (onStack.has(w)) {
+ lowlink.set(v, Math.min(lowlink.get(v) ?? 0, index.get(w) ?? 0));
+ }
+ }
+
+ if (lowlink.get(v) === index.get(v)) {
+ const group: string[] = [];
+ let w = '';
+ do {
+ const popped = stack.pop();
+ if (popped === undefined) break;
+ w = popped;
+ onStack.delete(w);
+ group.push(w);
+ } while (w !== v);
+ groups.push(group);
+ }
+ };
+
+ for (const n of nodes) if (!index.has(n)) strongconnect(n);
+ return groups;
+}
+
+const sccGroups = computeSccGroups();
+
+const rel = (p: string) => relative(APP_SRC, p);
+
+const offending = sccGroups
+ .filter((group) => group.length > 1)
+ .filter(
+ (group) =>
+ group.some((p) => p.startsWith(LIB_DIR)) && group.some((p) => p.startsWith(EDITOR_DIR)),
+ );
+
+const buildReport = (): string => {
+ const blocks = offending.map((group) => {
+ const members = new Set(group);
+ const closing = edges
+ .filter(
+ (e) =>
+ members.has(e.from) &&
+ members.has(e.to) &&
+ e.from.startsWith(LIB_DIR) &&
+ e.to.startsWith(EDITOR_DIR),
+ )
+ .map((e) => ` ${rel(e.from)}:${e.line} → ${rel(e.to)} (${e.spec})`)
+ .sort();
+ const hasDocContext = members.has(DOCUMENT_CONTEXT);
+ return [
+ ` • lib/↔editor/ value-import cycle (${group.length} modules)${
+ hasDocContext ? ' — includes editor/DocumentContext.tsx' : ''
+ }:`,
+ ` ${group.map(rel).sort().join('\n ')}`,
+ ` lib/ → editor/ VALUE edge(s) that close it (the layering inversion to cut):`,
+ ...closing,
+ ].join('\n');
+ });
+
+ return [
+ `Found ${offending.length} runtime (value-import) cycle(s) crossing the lib/ ↔ editor/ boundary.`,
+ `This is the latent SCC behind the CI flake "Export named 'useDocumentTransition' not found in module DocumentContext.tsx".`,
+ ``,
+ ...blocks,
+ ``,
+ `Fix: cut the lib/ → editor/ value-import edge(s) listed above — they are the layering`,
+ `inversion that closes the cycle. Dependency-invert: move the imported value into lib/, or`,
+ `pass it as a prop/parameter from an App-tier host. 'import type' edges are ignored by this`,
+ `guard, so a type-only re-point will NOT satisfy it.`,
+ ].join('\n');
+};
+
+describe('editor module graph layering', () => {
+ test('static import-graph analyser sees both sides of the lib/ ↔ editor/ boundary', () => {
+ expect(fileSet.has(DOCUMENT_CONTEXT)).toBe(true);
+ expect(fileSet.has(CONFIG_PROVIDER)).toBe(true);
+ expect([...fileSet].filter((p) => p.startsWith(EDITOR_DIR)).length).toBeGreaterThan(10);
+ expect([...fileSet].filter((p) => p.startsWith(LIB_DIR)).length).toBeGreaterThan(10);
+ expect(adjacency.get(DOCUMENT_CONTEXT)?.size ?? 0).toBeGreaterThan(0);
+ expect(adjacency.get(CONFIG_PROVIDER)?.size ?? 0).toBeGreaterThan(0);
+ });
+
+ test('no runtime (value-import) cycle crosses the lib/ ↔ editor/ boundary', () => {
+ expect(offending.length === 0 ? '' : buildReport()).toBe('');
+ });
+});
diff --git a/packages/app/src/editor/provider-pool.test.ts b/packages/app/src/editor/provider-pool.test.ts
index dcec03ca7..738cd7671 100644
--- a/packages/app/src/editor/provider-pool.test.ts
+++ b/packages/app/src/editor/provider-pool.test.ts
@@ -4,9 +4,10 @@ import { setTimeout as wait } from 'node:timers/promises';
import { PROTOCOL_VERSION } from '@inkeep/open-knowledge-core';
import { parseHocuspocusAuthToken } from '@inkeep/open-knowledge-server';
import * as Y from 'yjs';
+import { buildAuthToken } from '../lib/auth-token';
import { __resetCardinalityWarnings, getCollector } from '../lib/perf/collector';
import type { ClientPersistenceProvider } from './client-persistence';
-import { buildAuthToken, ProviderPool } from './provider-pool';
+import { ProviderPool } from './provider-pool';
import {
__resetSyncPromiseCache,
__syncPromiseCacheSize,
diff --git a/packages/app/src/editor/provider-pool.ts b/packages/app/src/editor/provider-pool.ts
index 217ada58c..6f40ce64b 100644
--- a/packages/app/src/editor/provider-pool.ts
+++ b/packages/app/src/editor/provider-pool.ts
@@ -1,12 +1,9 @@
import { HocuspocusProvider } from '@hocuspocus/provider';
import { LINEAGE_EPOCH_KEY, MarkdownManager } from '@inkeep/open-knowledge-core';
-import type {
- HocuspocusAuthRejectionReason,
- HocuspocusAuthToken,
-} from '@inkeep/open-knowledge-server';
+import type { HocuspocusAuthRejectionReason } from '@inkeep/open-knowledge-server';
import { getSchema } from '@tiptap/core';
import * as Y from 'yjs';
-import { browserClientVersionTokenFields } from '../lib/client-version';
+import { buildAuthToken } from '../lib/auth-token';
import { readNumericOverride } from '../lib/perf/env-override';
import { mark } from '../lib/perf/mark';
import { emitColdMountChild } from '../lib/perf/otel-spans';
@@ -186,29 +183,6 @@ const MAX_BUFFER_BYTES = readNumericOverride('MAX_BUFFER_BYTES', 1 * 1024 * 1024
*/
export const MAX_POOL = readNumericOverride('MAX_POOL', 10);
-export function buildAuthToken(
- tabIdentity: { principalId: string; tabSessionId: string } | null,
- expectedServerInstanceId: string | null,
- expectedBranch: string | null = null,
- expectedDocLineageEpoch: string | null = null,
-): string {
- const claim: HocuspocusAuthToken = { ...browserClientVersionTokenFields() };
- if (tabIdentity !== null) {
- claim.principalId = tabIdentity.principalId;
- claim.tabSessionId = tabIdentity.tabSessionId;
- }
- if (expectedServerInstanceId !== null && expectedServerInstanceId.length > 0) {
- claim.expectedServerInstanceId = expectedServerInstanceId;
- }
- if (expectedBranch !== null && expectedBranch.length > 0) {
- claim.expectedBranch = expectedBranch;
- }
- if (expectedDocLineageEpoch !== null && expectedDocLineageEpoch.length > 0) {
- claim.expectedDocLineageEpoch = expectedDocLineageEpoch;
- }
- return JSON.stringify(claim);
-}
-
/**
* LRU pool of HocuspocusProvider instances. Plain TS class — not a React hook.
* Owns WebSocket connections, survives React re-renders.
diff --git a/packages/app/src/lib/auth-token.ts b/packages/app/src/lib/auth-token.ts
new file mode 100644
index 000000000..6a9d7888f
--- /dev/null
+++ b/packages/app/src/lib/auth-token.ts
@@ -0,0 +1,25 @@
+import type { HocuspocusAuthToken } from '@inkeep/open-knowledge-server';
+import { browserClientVersionTokenFields } from './client-version';
+
+export function buildAuthToken(
+ tabIdentity: { principalId: string; tabSessionId: string } | null,
+ expectedServerInstanceId: string | null,
+ expectedBranch: string | null = null,
+ expectedDocLineageEpoch: string | null = null,
+): string {
+ const claim: HocuspocusAuthToken = { ...browserClientVersionTokenFields() };
+ if (tabIdentity !== null) {
+ claim.principalId = tabIdentity.principalId;
+ claim.tabSessionId = tabIdentity.tabSessionId;
+ }
+ if (expectedServerInstanceId !== null && expectedServerInstanceId.length > 0) {
+ claim.expectedServerInstanceId = expectedServerInstanceId;
+ }
+ if (expectedBranch !== null && expectedBranch.length > 0) {
+ claim.expectedBranch = expectedBranch;
+ }
+ if (expectedDocLineageEpoch !== null && expectedDocLineageEpoch.length > 0) {
+ claim.expectedDocLineageEpoch = expectedDocLineageEpoch;
+ }
+ return JSON.stringify(claim);
+}
diff --git a/packages/app/src/lib/config-provider.dom.test.tsx b/packages/app/src/lib/config-provider.dom.test.tsx
index 02a94d23c..51c60daa1 100644
--- a/packages/app/src/lib/config-provider.dom.test.tsx
+++ b/packages/app/src/lib/config-provider.dom.test.tsx
@@ -1,11 +1,6 @@
import { afterEach, beforeEach, describe, expect, mock, spyOn, test } from 'bun:test';
import { cleanup, render, screen } from '@testing-library/react';
-mock.module('@/editor/DocumentContext', () => ({
- useDocumentContext: () => ({ collabUrl: null }),
- DocumentProvider: ({ children }: { children: React.ReactNode }) => children,
-}));
-
mock.module('@/hooks/use-theme-bridge', () => ({
useThemeBridge: () => {},
}));
@@ -46,7 +41,7 @@ describe('ConfigProvider runtime (Tier-3)', () => {
test('propagates the all-null value when collabUrl is null (cold-start window)', () => {
render(
- <ConfigProvider>
+ <ConfigProvider collabUrl={null}>
<Consumer />
</ConfigProvider>,
);
diff --git a/packages/app/src/lib/config-provider.tsx b/packages/app/src/lib/config-provider.tsx
index 16ed0e4fe..d8deedb71 100644
--- a/packages/app/src/lib/config-provider.tsx
+++ b/packages/app/src/lib/config-provider.tsx
@@ -15,9 +15,8 @@ import {
import { useTheme } from 'next-themes';
import { type ReactNode, useEffect, useState } from 'react';
import * as Y from 'yjs';
-import { useDocumentContext } from '@/editor/DocumentContext';
-import { buildAuthToken } from '@/editor/provider-pool';
import { useThemeBridge } from '@/hooks/use-theme-bridge';
+import { buildAuthToken } from './auth-token';
import { ConfigContext, type ConfigContextValue } from './config-context';
import { useServerInstanceId } from './server-instance-store';
@@ -98,8 +97,13 @@ function makeOkignoreBinding(collabUrl: string, serverInstanceId: string | null)
return { binding, provider, cleanup };
}
-export function ConfigProvider({ children }: { children: ReactNode }) {
- const { collabUrl } = useDocumentContext();
+export function ConfigProvider({
+ collabUrl,
+ children,
+}: {
+ collabUrl: string | null;
+ children: ReactNode;
+}) {
const serverInstanceId = useServerInstanceId();
const [userState, setUserState] = useState<{
binding: ConfigBinding;
diff --git a/packages/app/src/lib/config-provider.user-synced.dom.test.tsx b/packages/app/src/lib/config-provider.user-synced.dom.test.tsx
index c28d9a31f..a09b59ed3 100644
--- a/packages/app/src/lib/config-provider.user-synced.dom.test.tsx
+++ b/packages/app/src/lib/config-provider.user-synced.dom.test.tsx
@@ -91,11 +91,6 @@ function makeFakeOkignoreBinding(): OkignoreBinding {
} as unknown as OkignoreBinding;
}
-mock.module('@/editor/DocumentContext', () => ({
- useDocumentContext: () => ({ collabUrl: 'ws://test.invalid' }),
- DocumentProvider: ({ children }: { children: React.ReactNode }) => children,
-}));
-
mock.module('@/hooks/use-theme-bridge', () => ({
useThemeBridge: (bridge: unknown, theme: string) => {
useThemeBridgeCalls.push([bridge, theme]);
@@ -134,7 +129,7 @@ mock.module('@hocuspocus/provider', () => {
return { HocuspocusProvider: FakeHocuspocusProvider };
});
-mock.module('@/editor/provider-pool', () => ({
+mock.module('@/lib/auth-token', () => ({
buildAuthToken: (...args: readonly unknown[]) => {
buildAuthTokenCalls.push(args);
return 'test-auth-token';
@@ -201,7 +196,7 @@ describe('ConfigProvider — userSynced behavioral wiring (Tier-3)', () => {
test('userSynced reads false until the binding fires its synced listener, then flips to true', () => {
render(
- <ConfigProvider>
+ <ConfigProvider collabUrl="ws://test.invalid">
<UserSyncedConsumer />
</ConfigProvider>,
);
@@ -222,7 +217,7 @@ describe('ConfigProvider — userSynced behavioral wiring (Tier-3)', () => {
userHasSyncedSeed = true;
render(
- <ConfigProvider>
+ <ConfigProvider collabUrl="ws://test.invalid">
<UserSyncedConsumer />
</ConfigProvider>,
);
@@ -232,7 +227,7 @@ describe('ConfigProvider — userSynced behavioral wiring (Tier-3)', () => {
test('opens user, project, and project-local bindings and exposes the merged context shape', async () => {
render(
- <ConfigProvider>
+ <ConfigProvider collabUrl="ws://test.invalid">
<ConfigContextProbe />
</ConfigProvider>,
);
@@ -264,7 +259,7 @@ describe('ConfigProvider — userSynced behavioral wiring (Tier-3)', () => {
test('projectLocalSynced flips from its hasSynced seed and cleans up on unmount', async () => {
const { unmount } = render(
- <ConfigProvider>
+ <ConfigProvider collabUrl="ws://test.invalid">
<ConfigContextProbe />
</ConfigProvider>,
);
@@ -304,7 +299,7 @@ describe('ConfigProvider — userSynced behavioral wiring (Tier-3)', () => {
mergedConfig = { appearance: {} };
render(
- <ConfigProvider>
+ <ConfigProvider collabUrl="ws://test.invalid">
<ConfigContextProbe />
</ConfigProvider>,
);
@@ -321,7 +316,7 @@ describe('ConfigProvider — userSynced behavioral wiring (Tier-3)', () => {
setServerInstanceId('epoch-threading-test');
render(
- <ConfigProvider>
+ <ConfigProvider collabUrl="ws://test.invalid">
<ConfigContextProbe />
</ConfigProvider>,
);
@@ -339,7 +334,7 @@ describe('ConfigProvider — userSynced behavioral wiring (Tier-3)', () => {
const consoleWarnSpy = spyOn(console, 'warn').mockImplementation(() => {});
render(
- <ConfigProvider>
+ <ConfigProvider collabUrl="ws://test.invalid">
<ConfigContextProbe />
</ConfigProvider>,
);
diff --git a/packages/app/tests/integration/client-version-no-regression.test.ts b/packages/app/tests/integration/client-version-no-regression.test.ts
index c3f3c5c3f..dba4fe3c6 100644
--- a/packages/app/tests/integration/client-version-no-regression.test.ts
+++ b/packages/app/tests/integration/client-version-no-regression.test.ts
@@ -2,7 +2,7 @@ import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { HocuspocusProvider } from '@hocuspocus/provider';
import { clientVersionHeaders } from '@inkeep/open-knowledge-core';
import * as Y from 'yjs';
-import { buildAuthToken } from '../../src/editor/provider-pool';
+import { buildAuthToken } from '../../src/lib/auth-token';
import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
import { createTestServer, type TestServer, waitForSync } from './test-harness';
diff --git a/packages/app/tests/integration/config-doc-server-instance-recovery.test.ts b/packages/app/tests/integration/config-doc-server-instance-recovery.test.ts
index 40dd72229..8edfc34c4 100644
--- a/packages/app/tests/integration/config-doc-server-instance-recovery.test.ts
+++ b/packages/app/tests/integration/config-doc-server-instance-recovery.test.ts
@@ -5,7 +5,7 @@ import { setTimeout as wait } from 'node:timers/promises';
import { HocuspocusProvider } from '@hocuspocus/provider';
import { CONFIG_DOC_NAME_OKIGNORE } from '@inkeep/open-knowledge-core';
import * as Y from 'yjs';
-import { buildAuthToken } from '../../src/editor/provider-pool';
+import { buildAuthToken } from '../../src/lib/auth-token';
import { createRestartableServer, pollUntil, waitForSync } from './test-harness';
const cleanups: Array<() => Promise<void> | void> = [];