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