Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Reuse warm document derivations for docs navigation (#6755)

Nick Gomez1f318c5b2dd9
diff --git a/.changeset/reuse-warm-document-derivations.md b/.changeset/reuse-warm-document-derivations.md
new file mode 100644
index 000000000..a23c76284
--- /dev/null
+++ b/.changeset/reuse-warm-document-derivations.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Keep document navigation responsive when reopening a large document by avoiding repeated statistics and wiki-link resolution work.
diff --git a/packages/app/src/editor/extensions/wiki-link.resolution-cache.test.ts b/packages/app/src/editor/extensions/wiki-link.resolution-cache.test.ts
new file mode 100644
index 000000000..94e212529
--- /dev/null
+++ b/packages/app/src/editor/extensions/wiki-link.resolution-cache.test.ts
@@ -0,0 +1,73 @@
+import * as wikiLinkResolve from '@inkeep/open-knowledge-core/utils/wiki-link-resolve';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import * as linkTargetIntent from '../../components/link-target-intent';
+import {
+ resetLinkValidationPolicyForTest,
+ setLinkValidationVisible,
+} from '../link-validation-policy';
+import {
+ buildPagesByBasenameIndex,
+ buildPagesBySlugIndex,
+ type PageListCacheSnapshot,
+} from '../page-list-cache';
+import { getWikiLinkResolutionState } from './wiki-link';
+import { toWikiLinkSlug } from './wiki-link-helpers';
+
+function snapshot(names: string[]): PageListCacheSnapshot {
+ const pages = new Set(names);
+ return {
+ pages,
+ folderPaths: new Set(),
+ pagesBySlug: buildPagesBySlugIndex(pages, toWikiLinkSlug),
+ pagesByBasename: buildPagesByBasenameIndex(pages, toWikiLinkSlug),
+ };
+}
+
+beforeEach(() => resetLinkValidationPolicyForTest());
+
+afterEach(() => {
+ vi.restoreAllMocks();
+ resetLinkValidationPolicyForTest();
+});
+
+describe('wiki-link resolution reuse', () => {
+ test('repeated targets in one namespace are resolved once', () => {
+ const resolve = vi.spyOn(wikiLinkResolve, 'resolveWikiLinkTarget');
+ const intent = vi.spyOn(linkTargetIntent, 'resolveLinkTargetIntent');
+ const cache = snapshot(['note']);
+ for (let i = 0; i < 4; i++) {
+ expect(getWikiLinkResolutionState('note', null, cache)).toBe('resolved');
+ }
+ expect(resolve).toHaveBeenCalledTimes(1);
+ expect(intent).toHaveBeenCalledTimes(1);
+ });
+
+ test('a new namespace cannot reuse the previous namespace’s answer', () => {
+ expect(getWikiLinkResolutionState('note', null, snapshot([]))).toBe('unresolved');
+ expect(getWikiLinkResolutionState('note', null, snapshot(['note']))).toBe('resolved');
+ });
+
+ test('validation visibility is part of the resolution context', () => {
+ const cache = snapshot([]);
+ expect(getWikiLinkResolutionState('missing', null, cache)).toBe('unresolved');
+ setLinkValidationVisible(false);
+ expect(getWikiLinkResolutionState('missing', null, cache)).toBeNull();
+ setLinkValidationVisible(true);
+ expect(getWikiLinkResolutionState('missing', null, cache)).toBe('unresolved');
+ });
+
+ test('links with different anchors retain their resolution state', () => {
+ const cache = snapshot(['note']);
+ expect(getWikiLinkResolutionState('note', 'one', cache)).toBe('resolved');
+ expect(getWikiLinkResolutionState('note', 'two', cache)).toBe('resolved');
+ });
+
+ test('resolution reuse remains bounded', () => {
+ const resolve = vi.spyOn(wikiLinkResolve, 'resolveWikiLinkTarget');
+ const cache = snapshot(['note']);
+ expect(getWikiLinkResolutionState('note', null, cache)).toBe('resolved');
+ for (let i = 0; i < 512; i++) getWikiLinkResolutionState(`missing-${i}`, null, cache);
+ expect(getWikiLinkResolutionState('note', null, cache)).toBe('resolved');
+ expect(resolve).toHaveBeenCalledTimes(514);
+ });
+});
diff --git a/packages/app/src/editor/extensions/wiki-link.ts b/packages/app/src/editor/extensions/wiki-link.ts
index 0a8d96861..cf51a12c1 100644
--- a/packages/app/src/editor/extensions/wiki-link.ts
+++ b/packages/app/src/editor/extensions/wiki-link.ts
@@ -88,6 +88,9 @@ function buildWikiLinkChipDom(params: {
return { dom, iconSpan };
}
+const resolutionStates = new WeakMap<PageListCacheSnapshot, Map<string, string | null>>();
+const RESOLUTION_CACHE_LIMIT = 512;
+
export function getWikiLinkIcon(
target: string,
cache: PageListCacheSnapshot | null,
@@ -106,6 +109,26 @@ export function getWikiLinkResolutionState(
target: string,
anchor: string | null,
cache: PageListCacheSnapshot | null,
+): string | null {
+ if (!cache) return computeWikiLinkResolutionState(target, anchor, cache);
+ let states = resolutionStates.get(cache);
+ if (!states) {
+ states = new Map();
+ resolutionStates.set(cache, states);
+ }
+ const key = JSON.stringify([target, anchor, isLinkValidationVisible()]);
+ const cached = states.get(key);
+ if (cached !== undefined) return cached;
+ const state = computeWikiLinkResolutionState(target, anchor, cache);
+ if (states.size >= RESOLUTION_CACHE_LIMIT) states.clear();
+ states.set(key, state);
+ return state;
+}
+
+function computeWikiLinkResolutionState(
+ target: string,
+ anchor: string | null,
+ cache: PageListCacheSnapshot | null,
): string | null {
if (!target) return null;
const classified = resolveWikiLinkTarget(target, anchor, cache ?? new Set<string>());
diff --git a/packages/app/src/hooks/use-document-stats.dom.test.tsx b/packages/app/src/hooks/use-document-stats.dom.test.tsx
index b80730976..9427b8c16 100644
--- a/packages/app/src/hooks/use-document-stats.dom.test.tsx
+++ b/packages/app/src/hooks/use-document-stats.dom.test.tsx
@@ -1,8 +1,9 @@
import type { HocuspocusProvider } from '@hocuspocus/provider';
import { isEditableTextDocFile } from '@inkeep/open-knowledge-core';
-import { cleanup, renderHook, waitFor } from '@testing-library/react';
-import { afterEach, describe, expect, test } from 'vitest';
+import { act, cleanup, renderHook, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, test, vi } from 'vitest';
import * as Y from 'yjs';
+import * as documentStats from '@/lib/document-stats';
import { useDocumentStats } from './use-document-stats';
function fakeProvider(source: string, docName: string): HocuspocusProvider {
@@ -14,9 +15,69 @@ function fakeProvider(source: string, docName: string): HocuspocusProvider {
} as unknown as HocuspocusProvider;
}
-afterEach(() => cleanup());
+afterEach(() => {
+ cleanup();
+ vi.restoreAllMocks();
+});
describe('useDocumentStats', () => {
+ test('reopening unchanged content reuses its derived statistics', () => {
+ const compute = vi.spyOn(documentStats, 'computeBodyStats');
+ const first = fakeProvider('**one** `two`', 'first');
+ const second = fakeProvider('other document', 'second');
+ const { result, rerender } = renderHook(
+ ({ provider, docName }) => useDocumentStats(provider, docName),
+ { initialProps: { provider: first, docName: 'first' } },
+ );
+ expect(result.current).toEqual({ words: 2, chars: 7, tokens: 2 });
+ rerender({ provider: second, docName: 'second' });
+ rerender({ provider: first, docName: 'first' });
+ expect(result.current).toEqual({ words: 2, chars: 7, tokens: 2 });
+ expect(compute).toHaveBeenCalledTimes(2);
+ });
+
+ test('reopening content edited while hidden recomputes its statistics', () => {
+ const compute = vi.spyOn(documentStats, 'computeBodyStats');
+ const first = fakeProvider('**one** `two`', 'first');
+ const second = fakeProvider('other document', 'second');
+ const { result, rerender } = renderHook(
+ ({ provider, docName }) => useDocumentStats(provider, docName),
+ { initialProps: { provider: first, docName: 'first' } },
+ );
+ rerender({ provider: second, docName: 'second' });
+ first.document.getText('source').insert(first.document.getText('source').length, ' three');
+ rerender({ provider: first, docName: 'first' });
+ expect(result.current).toEqual({ words: 3, chars: 13, tokens: 4 });
+ expect(compute).toHaveBeenCalledTimes(3);
+ });
+
+ test('an active edit still refreshes statistics', async () => {
+ const provider = fakeProvider('one', 'first');
+ const { result } = renderHook(() => useDocumentStats(provider, 'first'));
+ act(() => provider.document.getText('source').insert(3, ' two'));
+ await waitFor(() => expect(result.current).toEqual({ words: 2, chars: 7, tokens: 2 }));
+ });
+
+ test('a new document with the same name cannot reuse another document’s statistics', () => {
+ const first = fakeProvider('one', 'first');
+ const replacement = fakeProvider('one two', 'first');
+ const { result, rerender } = renderHook(({ provider }) => useDocumentStats(provider, 'first'), {
+ initialProps: { provider: first },
+ });
+ rerender({ provider: replacement });
+ expect(result.current).toEqual({ words: 2, chars: 7, tokens: 2 });
+ });
+
+ test('changing the file kind cannot reuse Markdown statistics for literal text', () => {
+ const provider = fakeProvider('**one**', 'first');
+ const { result, rerender } = renderHook(({ docName }) => useDocumentStats(provider, docName), {
+ initialProps: { docName: 'first.md' },
+ });
+ expect(result.current).toEqual({ words: 1, chars: 3, tokens: 1 });
+ rerender({ docName: 'first.csv' });
+ expect(result.current).toEqual({ words: 1, chars: 7, tokens: 2 });
+ });
+
test.each([
{
docName: 'glossary.csv',
diff --git a/packages/app/src/hooks/use-document-stats.ts b/packages/app/src/hooks/use-document-stats.ts
index 777e4e0c7..601b9a0e5 100644
--- a/packages/app/src/hooks/use-document-stats.ts
+++ b/packages/app/src/hooks/use-document-stats.ts
@@ -1,6 +1,7 @@
import type { HocuspocusProvider } from '@hocuspocus/provider';
import { isEditableTextDocFile } from '@inkeep/open-knowledge-core/constants/code-languages';
import { useEffect, useState } from 'react';
+import type { Text as YText } from 'yjs';
import {
computeBodyStats,
computePlainTextStats,
@@ -9,6 +10,10 @@ import {
} from '@/lib/document-stats';
const STATS_DEBOUNCE_MS = 300;
+const statsCache = new WeakMap<
+ YText,
+ { source: string; plainText: boolean; stats: DocumentStats }
+>();
export function useDocumentStats(
provider: HocuspocusProvider | null,
@@ -23,15 +28,22 @@ export function useDocumentStats(
}
const ytext = provider.document.getText('source');
- const computeStats = isEditableTextDocFile(activeDocName)
- ? computePlainTextStats
- : computeBodyStats;
+ const plainText = isEditableTextDocFile(activeDocName);
+ const computeStats = plainText ? computePlainTextStats : computeBodyStats;
let cancelled = false;
let timeout: ReturnType<typeof setTimeout> | null = null;
function compute() {
if (cancelled) return;
- setStats(computeStats(ytext.toString()));
+ const source = ytext.toString();
+ const cached = statsCache.get(ytext);
+ if (cached?.source === source && cached.plainText === plainText) {
+ setStats(cached.stats);
+ } else {
+ const nextStats = computeStats(source);
+ statsCache.set(ytext, { source, plainText, stats: nextStats });
+ setStats(nextStats);
+ }
}
compute();