Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.tsxindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsxindex 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.tsxindex 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.tsxindex 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.tsindex 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.tsindex 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> = [];