Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): refresh validation state without reopening files (#3035)

serafin-garcia15f3e98ac0d2
diff --git a/.changeset/audit-on-lint-config-change.md b/.changeset/audit-on-lint-config-change.md
new file mode 100644
index 000000000..a5d5e2471
--- /dev/null
+++ b/.changeset/audit-on-lint-config-change.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Keep validation state current instead of waiting for each file to be opened. Sidebar highlights and problem counts are now correct when you open a project, when you enable a plugin, when you toggle a rule, and when you switch git branches — previously a file only turned yellow once you clicked into it, switching a rule off left its counts standing, a branch switch kept showing the previous branch's problems, and project-wide state appeared only after visiting Problems → Project. Repeat audits over unchanged files are also much faster, and concurrent audits of the same project are coalesced into one. Audits no longer stall the server while they run: on a large knowledge base a project-wide audit previously blocked saving, search, opening files, and collaboration for its whole duration, and now runs in the background instead.
diff --git a/packages/app/src/App.dom.test.tsx b/packages/app/src/App.dom.test.tsx
index 7e216c5ee..ba43eb3ee 100644
--- a/packages/app/src/App.dom.test.tsx
+++ b/packages/app/src/App.dom.test.tsx
@@ -89,6 +89,18 @@ vi.doMock('@/components/PageListContext', () => ({
pagesBySlug,
pagesByBasename,
}),
+ // ValidationFreshness (mounted in the App body) reads the doc count through the
+ // optional variant to budget its on-open audit.
+ useOptionalPageList: () => ({
+ assetPaths,
+ filePaths,
+ folderPaths,
+ loading,
+ pageMeta,
+ pages,
+ pagesBySlug,
+ pagesByBasename,
+ }),
}));
vi.doMock('@/components/navigation-targets', () => ({
diff --git a/packages/app/src/components/DocPanel.dom.test.tsx b/packages/app/src/components/DocPanel.dom.test.tsx
index 7635e9d64..cd5a11448 100644
--- a/packages/app/src/components/DocPanel.dom.test.tsx
+++ b/packages/app/src/components/DocPanel.dom.test.tsx
@@ -65,6 +65,7 @@ vi.doMock('@/editor/useDocDiagnostics', () => ({
useDocDiagnostics: () => diagnosticsValue,
}));
vi.doMock('@/editor/validation-audit-client', () => ({
+ AUDIT_SUPERSEDED: 'audit-superseded',
runValidationAudit: async () => null,
useDocLinkFindings: () => [],
}));
diff --git a/packages/app/src/components/ProblemsPanel.dom.test.tsx b/packages/app/src/components/ProblemsPanel.dom.test.tsx
index c9d5b1132..2aa2b995e 100644
--- a/packages/app/src/components/ProblemsPanel.dom.test.tsx
+++ b/packages/app/src/components/ProblemsPanel.dom.test.tsx
@@ -33,7 +33,10 @@ vi.doMock('@lingui/core/macro', () => linguiMacroMock);
vi.doMock('@lingui/react/macro', () => linguiMacroMock);
let auditCalls = 0;
-let runLintAuditImpl: () => Promise<ValidationAuditResponse | null> = async () => null;
+/** Mirrors the client's exported sentinel; the mock below replaces the module. */
+const AUDIT_SUPERSEDED = 'audit-superseded' as const;
+let runLintAuditImpl: () => Promise<ValidationAuditResponse | null | typeof AUDIT_SUPERSEDED> =
+ async () => null;
let fixLintDocCalls: string[] = [];
let fixLintDocImpl: (docName: string) => Promise<{ ok: boolean; errorDetail?: string | null }> =
async () => ({ ok: true });
@@ -42,9 +45,17 @@ const toastError = vi.fn((_message: string) => {});
const toastSuccess = vi.fn((_message: string) => {});
vi.doMock('sonner', () => ({ toast: { error: toastError, success: toastSuccess } }));
+// Captured so a test can fire a config change the way a rule toggle does.
+const lintConfigListeners = new Set<() => void>();
+function emitLintConfigChangedForTest(): void {
+ for (const listener of lintConfigListeners) listener();
+}
vi.doMock('@/editor/lint-config-client', () => ({
emitLintConfigChanged: () => {},
- subscribeToLintConfigChanged: () => () => {},
+ subscribeToLintConfigChanged: (onChange: () => void) => {
+ lintConfigListeners.add(onChange);
+ return () => lintConfigListeners.delete(onChange);
+ },
fixLintDoc: (docName: string) => {
fixLintDocCalls.push(docName);
return fixLintDocImpl(docName);
@@ -56,6 +67,7 @@ vi.doMock('@/editor/lint-config-client', () => ({
}));
// The panel's project scope now consumes the unified audit plane.
vi.doMock('@/editor/validation-audit-client', () => ({
+ AUDIT_SUPERSEDED,
runValidationAudit: () => {
auditCalls += 1;
return runLintAuditImpl();
@@ -155,6 +167,7 @@ beforeEach(() => {
addPageCalls.length = 0;
toastError.mockClear();
toastSuccess.mockClear();
+ lintConfigListeners.clear();
});
afterEach(() => {
@@ -1214,4 +1227,150 @@ describe('ProblemsPanel — project scope', () => {
fireEvent.click(screen.getByTestId('panel-scope-doc'));
expect(screen.getByText('Hard tabs')).toBeTruthy();
});
+
+ test('a lint-config change refreshes a LOADED project snapshot in place', async () => {
+ runLintAuditImpl = async () =>
+ auditResult({ files: [{ file: 'notes.md', diagnostics: [diag({})] }] });
+ render(<ProblemsPanel docName="other" diagnostics={[]} />);
+ fireEvent.click(screen.getByTestId('panel-scope-project'));
+ await waitFor(() => expect(auditCalls).toBe(1));
+
+ // A rule toggle invalidates the snapshot's config: serving it on would show
+ // problems for rules the project no longer has.
+ emitLintConfigChangedForTest();
+ await waitFor(() => expect(auditCalls).toBe(2));
+ });
+
+ test('a lint-config change does NOT audit while the panel sits in doc scope', async () => {
+ runLintAuditImpl = async () => auditResult();
+ render(<ProblemsPanel docName="notes" diagnostics={[]} />);
+
+ emitLintConfigChangedForTest();
+ emitLintConfigChangedForTest();
+
+ // Doc scope holds no project snapshot to invalidate, so a config change must
+ // not provoke a whole-project walk here.
+ await new Promise((resolve) => setTimeout(resolve, 50));
+ expect(auditCalls).toBe(0);
+ });
+
+ test('a lint-config change does not resurrect a snapshot the panel never loaded', async () => {
+ runLintAuditImpl = async () => null;
+ render(<ProblemsPanel docName="notes" diagnostics={[]} />);
+ // Enter project scope and let the audit FAIL, so status is 'failed'.
+ fireEvent.click(screen.getByTestId('panel-scope-project'));
+ await waitFor(() => expect(auditCalls).toBe(1));
+ await waitFor(() => expect(screen.getByText(/could not be completed/i)).toBeTruthy());
+
+ emitLintConfigChangedForTest();
+ await new Promise((resolve) => setTimeout(resolve, 50));
+ // A failed run keeps its error until the user retries — the refresh
+ // affordance is the retry, not a config event.
+ expect(auditCalls).toBe(1);
+ });
+
+ test('a superseded walk re-loads in place instead of surfacing an error', async () => {
+ runLintAuditImpl = async () =>
+ auditResult({ files: [{ file: 'guides/setup.md', diagnostics: [diag({ line: 4 })] }] });
+ render(<ProblemsPanel docName="notes" diagnostics={[]} />);
+ fireEvent.click(screen.getByTestId('panel-scope-project'));
+ await waitFor(() => expect(screen.getByText('guides/setup.md')).toBeTruthy());
+ expect(auditCalls).toBe(1);
+
+ // The server abandons a walk whose config moved under it. The same config
+ // change drives the replacement, so the panel must neither render a failure
+ // nor sit on a spinner no later event clears.
+ runLintAuditImpl = async () => AUDIT_SUPERSEDED;
+ emitLintConfigChangedForTest();
+ await waitFor(() => expect(auditCalls).toBe(2));
+
+ runLintAuditImpl = async () =>
+ auditResult({ files: [{ file: 'guides/setup.md', diagnostics: [diag({ line: 4 })] }] });
+ emitLintConfigChangedForTest();
+ await waitFor(() => expect(auditCalls).toBe(3));
+ await waitFor(() => expect(screen.getByText('guides/setup.md')).toBeTruthy());
+ expect(screen.queryByText(/could not be completed/i)).toBeNull();
+ });
+
+ test('a superseded refresh leaves the panel on its previous plane, not a spinner', async () => {
+ runLintAuditImpl = async () =>
+ auditResult({ files: [{ file: 'guides/setup.md', diagnostics: [diag({ line: 4 })] }] });
+ render(<ProblemsPanel docName="notes" diagnostics={[]} />);
+ fireEvent.click(screen.getByTestId('panel-scope-project'));
+ await waitFor(() => expect(screen.getByText('guides/setup.md')).toBeTruthy());
+
+ // Refresh, and let the server abandon the walk. Nothing else is coming: the
+ // `lint-config` push that would carry a replacement has no reconnect replay,
+ // so the panel has to recover on its own or it sits on a spinner forever
+ // with its only retry affordance disabled.
+ runLintAuditImpl = async () => AUDIT_SUPERSEDED;
+ fireEvent.click(screen.getByLabelText('Re-run the project audit'));
+ await waitFor(() => expect(auditCalls).toBe(2));
+
+ await waitFor(() =>
+ expect(
+ (screen.getByLabelText('Re-run the project audit') as HTMLButtonElement).disabled,
+ ).toBe(false),
+ );
+ // The stale-but-real plane is still on screen, and no error was invented.
+ expect(screen.getByText('guides/setup.md')).toBeTruthy();
+ expect(screen.queryByText(/could not be completed/i)).toBeNull();
+ expect(screen.queryByRole('status')).toBeNull();
+
+ // And the recovered affordance actually works.
+ runLintAuditImpl = async () =>
+ auditResult({ files: [{ file: 'after-retry.md', diagnostics: [diag({})] }] });
+ fireEvent.click(screen.getByLabelText('Re-run the project audit'));
+ await waitFor(() => expect(screen.getByText('after-retry.md')).toBeTruthy());
+ });
+
+ test('a first activation that is superseded offers the retry rather than spinning', async () => {
+ // Nothing has ever loaded, so there is no plane to fall back to — the panel
+ // must still surface a reachable retry instead of an endless skeleton.
+ runLintAuditImpl = async () => AUDIT_SUPERSEDED;
+ render(<ProblemsPanel docName="notes" diagnostics={[]} />);
+ fireEvent.click(screen.getByTestId('panel-scope-project'));
+
+ await waitFor(() =>
+ expect(screen.getByText('The audit could not be completed. Try again.')).toBeTruthy(),
+ );
+ expect((screen.getByLabelText('Re-run the project audit') as HTMLButtonElement).disabled).toBe(
+ false,
+ );
+
+ runLintAuditImpl = async () =>
+ auditResult({ files: [{ file: 'retried.md', diagnostics: [diag({})] }] });
+ fireEvent.click(screen.getByLabelText('Re-run the project audit'));
+ await waitFor(() => expect(screen.getByText('retried.md')).toBeTruthy());
+ });
+
+ test('a superseded walk never overwrites a replacement load that started after it', async () => {
+ runLintAuditImpl = async () =>
+ auditResult({ files: [{ file: 'first.md', diagnostics: [diag({})] }] });
+ render(<ProblemsPanel docName="notes" diagnostics={[]} />);
+ fireEvent.click(screen.getByTestId('panel-scope-project'));
+ await waitFor(() => expect(screen.getByText('first.md')).toBeTruthy());
+
+ // Refresh into a walk the server will abandon, held open so a config change
+ // can start its replacement while it is still in flight.
+ let releaseSuperseded: () => void = () => {};
+ runLintAuditImpl = () =>
+ new Promise((resolve) => {
+ releaseSuperseded = () => resolve(AUDIT_SUPERSEDED);
+ });
+ fireEvent.click(screen.getByLabelText('Re-run the project audit'));
+ await waitFor(() => expect(auditCalls).toBe(2));
+
+ runLintAuditImpl = async () =>
+ auditResult({ files: [{ file: 'second.md', diagnostics: [diag({})] }] });
+ emitLintConfigChangedForTest();
+ await waitFor(() => expect(screen.getByText('second.md')).toBeTruthy());
+
+ // The abandoned walk settles last. Its fallback is the plane from BEFORE the
+ // replacement ran, so landing it would roll the panel back to stale truth.
+ releaseSuperseded();
+ await new Promise((resolve) => setTimeout(resolve, 50));
+ expect(screen.getByText('second.md')).toBeTruthy();
+ expect(screen.queryByText('first.md')).toBeNull();
+ });
});
diff --git a/packages/app/src/components/ProblemsPanel.tsx b/packages/app/src/components/ProblemsPanel.tsx
index 8bc54d509..fb2673b20 100644
--- a/packages/app/src/components/ProblemsPanel.tsx
+++ b/packages/app/src/components/ProblemsPanel.tsx
@@ -30,9 +30,13 @@ import {
} from '@/components/ui/panel';
import { Skeleton } from '@/components/ui/skeleton';
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
-import { fixLintDoc, useProjectLintConfig } from '@/editor/lint-config-client';
+import {
+ fixLintDoc,
+ subscribeToLintConfigChanged,
+ useProjectLintConfig,
+} from '@/editor/lint-config-client';
import { rememberPendingSourceNavigation } from '@/editor/source-editor-navigation';
-import { runValidationAudit } from '@/editor/validation-audit-client';
+import { AUDIT_SUPERSEDED, runValidationAudit } from '@/editor/validation-audit-client';
import { createPageFromSeedAndUpdate } from '@/lib/create-page';
import { filePathToDocName, hashFromDocName } from '@/lib/doc-hash';
import { openProjectPluginsSettings } from '@/lib/use-settings-route';
@@ -537,6 +541,22 @@ export function ProblemsPanel({
mountedRef.current = false;
};
}, []);
+ // Latest-ref for the config-change subscription below: that subscription is
+ // installed once and must not be torn down and re-added on every render, so it
+ // calls through this instead of closing over a particular render's state.
+ const onLintConfigChangedRef = useRef<() => void>(() => {});
+ // The last SETTLED audit plane, i.e. what an abandoned walk falls back to.
+ // A latest-ref rather than the `audit` closure because `loadAudit` runs from
+ // callbacks that outlive their render (a project sweep, a page create), and
+ // `loading` is deliberately never recorded so chained supersessions restore
+ // the last real plane instead of the spinner the previous one left behind.
+ const settledAuditRef = useRef<ProjectAuditState>({ status: 'idle' });
+ useEffect(() => {
+ if (audit.status !== 'loading') settledAuditRef.current = audit;
+ });
+ // Load generation, so restoring an abandoned walk's fallback cannot clobber a
+ // replacement load that started after it.
+ const loadGenRef = useRef(0);
const sorted = [...diagnostics].sort(compareDiagnostics);
const docFixableCount = countFixable(sorted);
@@ -572,8 +592,27 @@ export function ProblemsPanel({
}
async function loadAudit() {
+ loadGenRef.current += 1;
+ const generation = loadGenRef.current;
+ const fallback = settledAuditRef.current;
setAudit({ status: 'loading' });
const result = await runValidationAudit();
+ // A superseded walk carries no plane, so the panel keeps the one it had —
+ // briefly-stale counts, with the refresh affordance back. It must not wait
+ // for the replacement the config change schedules: the `lint-config` push
+ // that would deliver it has no reconnect replay, so a socket drop inside the
+ // server's debounce window loses it and leaves the panel on a spinner with
+ // refresh disabled, which nothing else can clear. A first activation has no
+ // plane to keep, so it degrades to the retryable failure state instead —
+ // that state's refresh button is the way out.
+ if (result === AUDIT_SUPERSEDED) {
+ // Skipped when a later load is already in flight: its own settlement is
+ // fresher than this fallback, and it owns the panel from here.
+ if (loadGenRef.current === generation && mountedRef.current) {
+ setAudit(fallback.status === 'idle' ? { status: 'failed' } : fallback);
+ }
+ return;
+ }
// A successful whole-project audit is full-plane truth — refresh the
// shared validation store (freshness trigger 1) so the file tree's tints
// update in the same pass. Deliberately BEFORE the mounted guard: the
@@ -639,6 +678,28 @@ export function ProblemsPanel({
if (next === 'project' && audit.status === 'idle') void loadAudit();
}
+ // A loaded project snapshot was computed under a lint config that a rule
+ // toggle has now replaced, so serving it on is showing problems for rules the
+ // project no longer has (and hiding ones it just gained). Refresh in place —
+ // only when a snapshot exists, so a config change never provokes a
+ // whole-project walk for a panel sitting in doc scope. The server can coalesce
+ // this with the file-tree freshness pass firing off the same event, but only
+ // while both requests are in flight together: this one goes out immediately
+ // and that pass debounces first, so the common case is two walks, not one.
+ useEffect(() => {
+ onLintConfigChangedRef.current = () => {
+ // Also while a walk is in flight: a config change landing mid-walk
+ // supersedes that walk, and this is what starts its replacement — the
+ // abandoned walk only restores the plane it had, which is stale under the
+ // new config. Still skipped when the panel has never loaded (a config
+ // change must not provoke a walk for one sitting in doc scope) and when a
+ // run failed, where the refresh affordance is deliberately the only retry.
+ if (audit.status === 'idle' || audit.status === 'failed') return;
+ void loadAudit();
+ };
+ });
+ useEffect(() => subscribeToLintConfigChanged(() => onLintConfigChangedRef.current()), []);
+
function handleNav(diagnostic: DiagnosticLike) {
const detail = lintNavDetailOf(diagnostic);
// Banked unconditionally: the visible editor (source line-jump, or the
diff --git a/packages/app/src/components/ValidationFreshness.dom.test.tsx b/packages/app/src/components/ValidationFreshness.dom.test.tsx
index 4afe99aba..ab723d9b7 100644
--- a/packages/app/src/components/ValidationFreshness.dom.test.tsx
+++ b/packages/app/src/components/ValidationFreshness.dom.test.tsx
@@ -1,15 +1,33 @@
/**
- * Behavioral tests for freshness trigger 3: a doc-persisted relay (CC1
- * `disk-ack` docName) re-validates JUST that doc via the scoped audit and
- * patches its shared-store entry — reserved/mermaid docNames are skipped, and
- * bursts debounce to one trailing fetch per doc.
+ * Behavioral tests for freshness triggers 3, 4 and 5.
+ *
+ * Trigger 3: a doc-persisted relay (CC1 `disk-ack` docName) re-validates JUST
+ * that doc via the scoped audit and patches its shared-store entry — reserved/
+ * mermaid docNames are skipped, and bursts debounce to one trailing fetch per doc.
+ *
+ * Trigger 4: a lint-config change re-audits the whole plane via the counts-only
+ * response, replacing the store — bursts coalesce to one walk, and a change
+ * landing mid-walk supersedes it rather than racing it.
+ *
+ * Trigger 5: opening a project audits the whole plane once, budgeted by doc
+ * count — it latches only once a run populates the store, so a page-count shift
+ * or a failed fetch during the settle delay does not strand it un-run, and a
+ * failed attempt is retried a bounded number of times.
*/
-import type { ValidationAuditResponse } from '@inkeep/open-knowledge-core';
+import type {
+ ValidationAuditCountsResponse,
+ ValidationAuditResponse,
+} from '@inkeep/open-knowledge-core';
import { cleanup, render, waitFor } from '@testing-library/react';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
-import { emitDocPersisted } from '@/lib/documents-events';
-import { getValidationSnapshot, resetValidationStoreForTest } from '@/lib/validation-store';
+import { emitLintConfigChanged } from '@/editor/lint-config-client';
+import { emitBranchChanged, emitDocPersisted } from '@/lib/documents-events';
+import {
+ getValidationSnapshot,
+ resetValidationStoreForTest,
+ subscribeToValidationStore,
+} from '@/lib/validation-store';
// Config context gates the whole subscriber (`validation.fileTreeIndicators`).
let mergedConfigValue: { validation?: { fileTreeIndicators?: boolean } } | null = null;
@@ -17,6 +35,13 @@ vi.doMock('@/lib/config-provider', () => ({
useConfigContext: () => ({ merged: mergedConfigValue }),
}));
+// Doc count is the on-open readiness signal. Empty by default so the trigger-3
+// and trigger-4 tests below see no on-open walk competing with their assertions.
+let mockPages = new Set<string>();
+vi.doMock('@/components/PageListContext', () => ({
+ useOptionalPageList: () => ({ pages: mockPages }),
+}));
+
const { ValidationFreshness } = await import('./ValidationFreshness');
const origFetch = globalThis.fetch;
@@ -29,14 +54,48 @@ let fetchBody: ValidationAuditResponse = {
warnings: [],
};
+let countsBody: ValidationAuditCountsResponse = {
+ files: [],
+ fileCount: 0,
+ errorCount: 0,
+ warningCount: 0,
+ warnings: [],
+};
+/** Set to delay the counts response so a supersede can be observed mid-walk. */
+let countsDelayMs = 0;
+/** Set non-200 to make the counts endpoint fail (server-unavailable path). */
+let countsStatus = 200;
+
beforeEach(() => {
resetValidationStoreForTest();
mergedConfigValue = null;
fetchUrls = [];
- globalThis.fetch = (async (url: RequestInfo | URL) => {
- fetchUrls.push(String(url));
- return new Response(JSON.stringify(fetchBody), {
- status: 200,
+ countsDelayMs = 0;
+ countsStatus = 200;
+ countsBody = { files: [], fileCount: 0, errorCount: 0, warningCount: 0, warnings: [] };
+ mockPages = new Set();
+ globalThis.fetch = (async (url: RequestInfo | URL, init?: RequestInit) => {
+ const href = String(url);
+ fetchUrls.push(href);
+ const isCounts = href.includes('counts=1');
+ // Snapshot the body/status at CALL time, not after the delay: a delayed
+ // walk must return the payload configured when it started, so a supersede
+ // test that reassigns `countsBody` mid-flight sees the first walk still
+ // carrying the stale body it would (wrongly) land if not aborted.
+ const bodyAtCall = isCounts ? countsBody : fetchBody;
+ const statusAtCall = isCounts ? countsStatus : 200;
+ if (isCounts && countsDelayMs > 0) {
+ await new Promise((resolve, reject) => {
+ const timer = setTimeout(resolve, countsDelayMs);
+ init?.signal?.addEventListener('abort', () => {
+ clearTimeout(timer);
+ reject(new DOMException('Aborted', 'AbortError'));
+ });
+ });
+ }
+ if (init?.signal?.aborted === true) throw new DOMException('Aborted', 'AbortError');
+ return new Response(JSON.stringify(bodyAtCall), {
+ status: statusAtCall,
headers: { 'content-type': 'application/json' },
});
}) as typeof fetch;
@@ -144,4 +203,415 @@ describe('ValidationFreshness', () => {
emitDocPersisted('a');
await waitFor(() => expect(getValidationSnapshot().has('a')).toBe(false), { timeout: 3000 });
});
+
+ describe('trigger 4: lint-config change', () => {
+ test('re-audits the whole plane and replaces the store', async () => {
+ countsBody = {
+ files: [
+ {
+ file: 'guides/setup.md',
+ lint: { errorCount: 2, warningCount: 1 },
+ links: { errorCount: 0, warningCount: 1 },
+ },
+ ],
+ fileCount: 12,
+ errorCount: 2,
+ warningCount: 2,
+ warnings: [],
+ };
+ render(<ValidationFreshness />);
+ // No walk until something actually changes — mounting must not audit.
+ await new Promise((resolve) => setTimeout(resolve, 900));
+ expect(fetchUrls).toEqual([]);
+
+ emitLintConfigChanged();
+
+ await waitFor(
+ () =>
+ expect(getValidationSnapshot().get('guides/setup')).toEqual({
+ errorCount: 2,
+ warningCount: 2,
+ }),
+ { timeout: 3000 },
+ );
+ // Counts-only, project scope: no `doc=`/`path=`, and no enumerated fetch.
+ expect(fetchUrls).toEqual(['/api/audit?counts=1']);
+ });
+
+ test('docs the new config no longer flags drop out of the snapshot', async () => {
+ render(<ValidationFreshness />);
+ countsBody = {
+ files: [
+ {
+ file: 'a.md',
+ lint: { errorCount: 0, warningCount: 3 },
+ links: { errorCount: 0, warningCount: 0 },
+ },
+ ],
+ fileCount: 1,
+ errorCount: 0,
+ warningCount: 3,
+ warnings: [],
+ };
+ emitLintConfigChanged();
+ await waitFor(() => expect(getValidationSnapshot().has('a')).toBe(true), { timeout: 3000 });
+
+ // The rule that produced those three warnings is switched off.
+ countsBody = { files: [], fileCount: 1, errorCount: 0, warningCount: 0, warnings: [] };
+ emitLintConfigChanged();
+ await waitFor(() => expect(getValidationSnapshot().has('a')).toBe(false), { timeout: 3000 });
+ });
+
+ test('a burst of toggles coalesces to one walk', async () => {
+ render(<ValidationFreshness />);
+ emitLintConfigChanged();
+ emitLintConfigChanged();
+ emitLintConfigChanged();
+ emitLintConfigChanged();
+
+ await waitFor(() => expect(fetchUrls).toHaveLength(1), { timeout: 3000 });
+ await new Promise((resolve) => setTimeout(resolve, 900));
+ expect(fetchUrls).toEqual(['/api/audit?counts=1']);
+ });
+
+ test('a change landing mid-walk supersedes it instead of racing it', async () => {
+ // Above the 750ms config debounce, so the first walk is genuinely still in
+ // flight when the second change fires. At 600ms (below the debounce) the
+ // first walk settled and wrote before the second even started, so the
+ // abort was a no-op against a completed request and this test passed
+ // purely because the later write clobbered the earlier one.
+ countsDelayMs = 1200;
+ countsBody = {
+ files: [
+ {
+ file: 'stale.md',
+ lint: { errorCount: 9, warningCount: 0 },
+ links: { errorCount: 0, warningCount: 0 },
+ },
+ ],
+ fileCount: 1,
+ errorCount: 9,
+ warningCount: 0,
+ warnings: [],
+ };
+ // Assert on every store notification, not just the final state: an
+ // unconditional store-clear would satisfy a final `has('stale') === false`
+ // without any abort. The superseded walk's result must never land, even
+ // for one render.
+ let staleEverPresent = false;
+ const unsubscribe = subscribeToValidationStore(() => {
+ if (getValidationSnapshot().has('stale')) staleEverPresent = true;
+ });
+ render(<ValidationFreshness />);
+ emitLintConfigChanged();
+ await waitFor(() => expect(fetchUrls).toHaveLength(1), { timeout: 3000 });
+
+ // Second change while the first walk is still in flight: its result must
+ // never reach the store, even though it was requested first — the abort
+ // of the in-flight walk is what this exercises.
+ countsBody = {
+ files: [
+ {
+ file: 'fresh.md',
+ lint: { errorCount: 0, warningCount: 1 },
+ links: { errorCount: 0, warningCount: 0 },
+ },
+ ],
+ fileCount: 1,
+ errorCount: 0,
+ warningCount: 1,
+ warnings: [],
+ };
+ emitLintConfigChanged();
+
+ await waitFor(() => expect(getValidationSnapshot().has('fresh')).toBe(true), {
+ timeout: 5000,
+ });
+ unsubscribe();
+ expect(staleEverPresent).toBe(false);
+ expect(getValidationSnapshot().has('stale')).toBe(false);
+ });
+
+ test('a failed audit keeps the prior snapshot (stale beats wrongly-clean)', async () => {
+ render(<ValidationFreshness />);
+ // A first config change succeeds and seeds the store.
+ countsBody = {
+ files: [
+ {
+ file: 'a.md',
+ lint: { errorCount: 0, warningCount: 2 },
+ links: { errorCount: 0, warningCount: 0 },
+ },
+ ],
+ fileCount: 1,
+ errorCount: 0,
+ warningCount: 2,
+ warnings: [],
+ };
+ emitLintConfigChanged();
+ await waitFor(() => expect(getValidationSnapshot().has('a')).toBe(true), { timeout: 3000 });
+
+ // A later config change lands while the server is unavailable (500). The
+ // null result must leave the prior entry standing rather than clear the
+ // store — an empty snapshot reads as "all files clean".
+ countsStatus = 500;
+ emitLintConfigChanged();
+ await waitFor(() => expect(fetchUrls).toHaveLength(2), { timeout: 3000 });
+ await new Promise((resolve) => setTimeout(resolve, 200));
+ expect(getValidationSnapshot().get('a')).toEqual({ errorCount: 0, warningCount: 2 });
+ });
+
+ test('is inert when the project turns file-tree indicators off', async () => {
+ mergedConfigValue = { validation: { fileTreeIndicators: false } };
+ render(<ValidationFreshness />);
+ emitLintConfigChanged();
+
+ await new Promise((resolve) => setTimeout(resolve, 900));
+ expect(fetchUrls).toEqual([]);
+ });
+ });
+
+ describe('trigger 4: branch switch', () => {
+ const docs = (n: number) => new Set(Array.from({ length: n }, (_, i) => `doc-${i}`));
+
+ test('re-audits the whole plane after the on-open walk has already run', async () => {
+ mockPages = docs(3);
+ countsBody = {
+ files: [
+ {
+ file: 'only-on-main.md',
+ lint: { errorCount: 1, warningCount: 0 },
+ links: { errorCount: 0, warningCount: 0 },
+ },
+ ],
+ fileCount: 3,
+ errorCount: 1,
+ warningCount: 0,
+ warnings: [],
+ };
+ render(<ValidationFreshness />);
+ // Let the on-open walk land first: a branch switch handled in-window has
+ // to re-audit even though that walk already populated the store.
+ await waitFor(() => expect(getValidationSnapshot().has('only-on-main')).toBe(true), {
+ timeout: 5000,
+ });
+ expect(fetchUrls).toHaveLength(1);
+
+ // Switching branches replaces the content set wholesale, so every entry
+ // in the store was produced by content that no longer exists.
+ countsBody = {
+ files: [
+ {
+ file: 'only-on-feature.md',
+ lint: { errorCount: 0, warningCount: 4 },
+ links: { errorCount: 0, warningCount: 0 },
+ },
+ ],
+ fileCount: 5,
+ errorCount: 0,
+ warningCount: 4,
+ warnings: [],
+ };
+ emitBranchChanged('feature/x');
+
+ await waitFor(
+ () =>
+ expect(getValidationSnapshot().get('only-on-feature')).toEqual({
+ errorCount: 0,
+ warningCount: 4,
+ }),
+ { timeout: 5000 },
+ );
+ expect(getValidationSnapshot().has('only-on-main')).toBe(false);
+ expect(fetchUrls).toEqual(['/api/audit?counts=1', '/api/audit?counts=1']);
+ });
+
+ test('is inert when the project turns file-tree indicators off', async () => {
+ mergedConfigValue = { validation: { fileTreeIndicators: false } };
+ render(<ValidationFreshness />);
+ emitBranchChanged('feature/x');
+
+ await new Promise((resolve) => setTimeout(resolve, 900));
+ expect(fetchUrls).toEqual([]);
+ });
+ });
+
+ describe('trigger 5: audit on project open', () => {
+ const docs = (n: number) => new Set(Array.from({ length: n }, (_, i) => `doc-${i}`));
+
+ test('audits once on open', async () => {
+ mockPages = docs(3);
+ countsBody = {
+ files: [
+ {
+ file: 'stale/from-last-session.md',
+ lint: { errorCount: 1, warningCount: 0 },
+ links: { errorCount: 0, warningCount: 0 },
+ },
+ ],
+ fileCount: 3,
+ errorCount: 1,
+ warningCount: 0,
+ warnings: [],
+ };
+ render(<ValidationFreshness />);
+
+ // Nothing in this session opened, wrote, or reconfigured anything — the
+ // whole point is that a project configured earlier is correct on arrival.
+ await waitFor(
+ () =>
+ expect(getValidationSnapshot().get('stale/from-last-session')).toEqual({
+ errorCount: 1,
+ warningCount: 0,
+ }),
+ { timeout: 5000 },
+ );
+ expect(fetchUrls).toEqual(['/api/audit?counts=1']);
+ });
+
+ test('audits on open regardless of project size — no doc-size cap', async () => {
+ // The Problems panel's on-demand audit and the config-change trigger both
+ // walk any project uncapped, so capping this one bought no protection and
+ // made the same project show a populated sidebar after a rule toggle and a
+ // bare one after a reopen. A size bound, if ever warranted, belongs in the
+ // audit engine where all three callers inherit it.
+ mockPages = docs(4000);
+ countsBody = {
+ files: [
+ {
+ file: 'big/doc.md',
+ lint: { errorCount: 0, warningCount: 2 },
+ links: { errorCount: 0, warningCount: 0 },
+ },
+ ],
+ fileCount: 4000,
+ errorCount: 0,
+ warningCount: 2,
+ warnings: [],
+ };
+ render(<ValidationFreshness />);
+
+ await waitFor(() => expect(fetchUrls).toEqual(['/api/audit?counts=1']), { timeout: 5000 });
+ expect(getValidationSnapshot().get('big/doc')).toEqual({ errorCount: 0, warningCount: 2 });
+ });
+
+ test('audits once, not again as the page list grows', async () => {
+ mockPages = docs(3);
+ const view = render(<ValidationFreshness />);
+ await waitFor(() => expect(fetchUrls).toHaveLength(1), { timeout: 5000 });
+
+ // Creating docs must not re-trigger a whole-project walk; per-doc freshness
+ // is trigger 3's job.
+ mockPages = docs(9);
+ view.rerender(<ValidationFreshness />);
+ await new Promise((resolve) => setTimeout(resolve, 2000));
+ expect(fetchUrls).toEqual(['/api/audit?counts=1']);
+ });
+
+ test('a page-count change during the settle delay does not strand the audit un-run', async () => {
+ mockPages = docs(3);
+ countsBody = {
+ files: [
+ {
+ file: 'stale/from-last-session.md',
+ lint: { errorCount: 1, warningCount: 0 },
+ links: { errorCount: 0, warningCount: 0 },
+ },
+ ],
+ fileCount: 3,
+ errorCount: 1,
+ warningCount: 0,
+ warnings: [],
+ };
+ const view = render(<ValidationFreshness />);
+ // A doc is added (optimistic create / background refetch) during the
+ // settle window, before the scheduled audit fires. The effect tears down
+ // and reschedules; latching at schedule time would have refused the
+ // reschedule and left the sidebar empty for the whole session.
+ mockPages = docs(4);
+ view.rerender(<ValidationFreshness />);
+
+ await waitFor(
+ () =>
+ expect(getValidationSnapshot().get('stale/from-last-session')).toEqual({
+ errorCount: 1,
+ warningCount: 0,
+ }),
+ { timeout: 5000 },
+ );
+ // The cancelled first schedule never fetched; only the rescheduled run did.
+ expect(fetchUrls).toEqual(['/api/audit?counts=1']);
+ });
+
+ test('holds until the doc count is known rather than auditing an empty project', async () => {
+ // An unresolved page list reads as 0; auditing then would race the list and
+ // spend a walk before the project is even known.
+ mockPages = new Set();
+ const view = render(<ValidationFreshness />);
+ await new Promise((resolve) => setTimeout(resolve, 2000));
+ expect(fetchUrls).toEqual([]);
+
+ mockPages = docs(2);
+ view.rerender(<ValidationFreshness />);
+ await waitFor(() => expect(fetchUrls).toEqual(['/api/audit?counts=1']), { timeout: 5000 });
+ });
+
+ test('is inert when the project turns file-tree indicators off', async () => {
+ mergedConfigValue = { validation: { fileTreeIndicators: false } };
+ mockPages = docs(3);
+ render(<ValidationFreshness />);
+
+ await new Promise((resolve) => setTimeout(resolve, 2500));
+ expect(fetchUrls).toEqual([]);
+ });
+
+ test('a failed first attempt retries instead of costing the whole session', async () => {
+ // The server is still finishing its own boot when the settle delay fires.
+ // Nothing else re-triggers this pass in a session where no doc is created
+ // or removed, so without a retry one 500 reinstates the bare sidebar for
+ // the rest of the session.
+ mockPages = docs(3);
+ countsStatus = 500;
+ render(<ValidationFreshness />);
+ await waitFor(() => expect(fetchUrls).toHaveLength(1), { timeout: 5000 });
+ expect(getValidationSnapshot().size).toBe(0);
+
+ countsStatus = 200;
+ countsBody = {
+ files: [
+ {
+ file: 'stale/from-last-session.md',
+ lint: { errorCount: 1, warningCount: 0 },
+ links: { errorCount: 0, warningCount: 0 },
+ },
+ ],
+ fileCount: 3,
+ errorCount: 1,
+ warningCount: 0,
+ warnings: [],
+ };
+
+ await waitFor(
+ () =>
+ expect(getValidationSnapshot().get('stale/from-last-session')).toEqual({
+ errorCount: 1,
+ warningCount: 0,
+ }),
+ { timeout: 10_000 },
+ );
+ });
+
+ test('the retry is bounded rather than an open-ended poll', async () => {
+ mockPages = docs(3);
+ countsStatus = 500;
+ render(<ValidationFreshness />);
+
+ // Three attempts total (1.2s, +1.5s, +3s), then the trigger gives up for
+ // the session — the manual audit and triggers 3-4 still cover it.
+ await waitFor(() => expect(fetchUrls).toHaveLength(3), { timeout: 15_000 });
+ // A fourth attempt would be due 6s after the third; wait past that.
+ await new Promise((resolve) => setTimeout(resolve, 7000));
+ expect(fetchUrls).toHaveLength(3);
+ });
+ });
});
diff --git a/packages/app/src/components/ValidationFreshness.tsx b/packages/app/src/components/ValidationFreshness.tsx
index 65f4078c1..debb62224 100644
--- a/packages/app/src/components/ValidationFreshness.tsx
+++ b/packages/app/src/components/ValidationFreshness.tsx
@@ -1,24 +1,97 @@
/**
- * Freshness trigger 3 of the shared validation store: when a doc's bytes reach
- * disk (CC1 `disk-ack`, relayed as the doc-persisted event), re-validate JUST
- * that doc via the scoped audit and patch its store entry. This heals the
- * silent false-negative where an agent writes a broken link (or a lint
- * problem) into a document nobody has open — its tree tint updates without a
- * whole-project walk.
+ * Freshness triggers 3, 4 and 5 of the shared validation store.
*
- * Debounced per doc: persistence flushes ack in bursts during active writing;
- * one trailing re-validate per doc per burst is enough for a tree tint.
+ * Trigger 3 — when a doc's bytes reach disk (CC1 `disk-ack`, relayed as the
+ * doc-persisted event), re-validate JUST that doc via the scoped audit and
+ * patch its store entry. This heals the silent false-negative where an agent
+ * writes a broken link (or a lint problem) into a document nobody has open —
+ * its tree tint updates without a whole-project walk. Debounced per doc:
+ * persistence flushes ack in bursts during active writing; one trailing
+ * re-validate per doc per burst is enough for a tree tint.
+ *
+ * Trigger 4 — when the world every entry was produced against stops holding, the
+ * whole plane is re-audited. Two signals qualify. A lint-config change (a plugin
+ * enabled, a rule toggled, a frontmatter schema edited) invalidates the config
+ * the counts were computed under; without this, enabling a plugin lights up
+ * nothing until you open files one at a time, and toggling a rule off leaves its
+ * counts standing. A branch switch invalidates the content itself — it replaces
+ * the content set wholesale in-window, with no reload to rebuild the plane, so
+ * the sidebar would otherwise keep showing the previous branch's problems until
+ * a config change or a per-doc write happened to trip triggers 3/4.
+ *
+ * Trigger 5 — once per project open, audit the plane so a project configured in
+ * an earlier session is correct on arrival. Triggers 2-4 all need something to
+ * HAPPEN in this session (a doc opened, a doc written, the config changed), so
+ * without this the store starts empty on every launch and a KB whose problems
+ * predate the session shows a bare sidebar until the user opens files one by one
+ * or runs the audit by hand — the original complaint, recurring at every launch.
+ *
+ * Triggers 4 and 5 are the two whole-project walks, so both are kept cheap the
+ * same ways: the counts-only plane rather than the enumerated one, and the server
+ * coalescing concurrent identical audits into one. Trigger 4 additionally
+ * debounces bursts and single-flights them across both its signals — a later
+ * invalidation landing mid-walk aborts the walk it supersedes, so a config
+ * change arriving just after a branch switch cannot be overwritten by the
+ * branch's older, now-stale result. Trigger 5 is a run-once latch that aborts
+ * only on unmount, latching once a run actually populates the store — and
+ * retrying a bounded number of times when one does not, because its only other
+ * retry signal is a doc count that in an ordinary reading session never moves
+ * again.
+ *
+ * Neither trigger caps by project size, deliberately. The Problems panel's
+ * on-demand audit has always walked any project uncapped, and trigger 4 does too,
+ * so capping trigger 5 alone bought no protection and made the product
+ * inconsistent — the same project would show a populated sidebar after a rule
+ * toggle and a bare one after a reopen. A size bound, if one is ever warranted,
+ * belongs in the audit engine where all three callers inherit it, not bolted onto
+ * one of them. What keeps the cost tolerable here is that the desktop server
+ * survives app quit (packaged builds spawn it detached — see
+ * `packages/desktop/README.md`), so reopening reattaches to a live server with a
+ * warm per-file cache; a genuinely cold walk happens once per server lifetime,
+ * not once per launch.
*/
-import { useEffect } from 'react';
-import { runValidationAudit } from '@/editor/validation-audit-client';
+import { useEffect, useRef } from 'react';
+import { useOptionalPageList } from '@/components/PageListContext';
+import { subscribeToLintConfigChanged } from '@/editor/lint-config-client';
+import {
+ AUDIT_SUPERSEDED,
+ runValidationAudit,
+ runValidationAuditCounts,
+} from '@/editor/validation-audit-client';
import { useConfigContext } from '@/lib/config-provider';
import { filePathToDocName } from '@/lib/doc-hash';
-import { subscribeToDocPersisted } from '@/lib/documents-events';
-import { patchDocValidationFromAudit } from '@/lib/validation-store';
+import { subscribeToBranchChanged, subscribeToDocPersisted } from '@/lib/documents-events';
+import { patchDocValidationFromAudit, replaceValidationFromCounts } from '@/lib/validation-store';
const REVALIDATE_DEBOUNCE_MS = 500;
+/**
+ * Longer than the per-doc debounce: a rule-by-rule pass through the Settings
+ * rule list emits one config-changed event per click, and each one would
+ * otherwise start a whole-project walk. Long enough to coalesce deliberate
+ * clicking, short enough that a single toggle still feels immediate. Branch
+ * switches share the window — they never burst, but a switch that lands during
+ * a toggle pass should fold into the same walk rather than add one.
+ */
+const PLANE_AUDIT_DEBOUNCE_MS = 750;
+
+/** Wait for the app's own boot work to settle before spending CPU on an audit. */
+const AUDIT_ON_OPEN_DELAY_MS = 1_200;
+
+/**
+ * Attempts the on-open walk gets before giving up for the session, and the
+ * first retry's delay (doubled per attempt). A doc count that never moves again
+ * is the ordinary case — nothing creates or removes a document in a session
+ * spent reading — so a single transient failure (the server still finishing its
+ * own boot, a 500) would otherwise cost the whole session the on-open pass and
+ * reinstate the bare sidebar this trigger exists to fill. Bounded rather than
+ * open-ended: past a few seconds the failure is not transient, and the manual
+ * audit plus triggers 3-4 still cover the session.
+ */
+const AUDIT_ON_OPEN_MAX_ATTEMPTS = 3;
+const AUDIT_ON_OPEN_RETRY_MS = 1_500;
+
/**
* DocNames the per-doc re-validate skips: reserved trees (`__system__`,
* `__config__/…`, `__skill__/…`, `__template__/…`, `__local__/…`, `__user__/…`)
@@ -29,12 +102,36 @@ function isAuditableDocName(docName: string): boolean {
return !docName.startsWith('__') && !/\.(mmd|mermaid)$/i.test(docName);
}
+/**
+ * The whole-project step shared by triggers 4 and 5: audit the counts-only plane
+ * and replace the store with it. A failed or superseded run leaves the previous
+ * entries alone — stale beats wrongly-clean, the same call the per-doc
+ * re-validate makes.
+ */
+async function auditProjectIntoStore(signal: AbortSignal): Promise<boolean> {
+ const result = await runValidationAuditCounts({ kind: 'project' }, signal);
+ // A superseded walk carries no plane; the config change that superseded it
+ // is the same one that schedules the replacement, so write nothing and stay
+ // unlatched rather than treating it as a completed run.
+ if (signal.aborted || result === null || result === AUDIT_SUPERSEDED) return false;
+ replaceValidationFromCounts(result.files);
+ return true;
+}
+
export function ValidationFreshness() {
// The per-doc re-validate exists to keep the file tree's indicators fresh;
// when the project turns those off (`validation.fileTreeIndicators`), skip
// the background work entirely instead of writing to a store nothing reads.
const { merged } = useConfigContext();
const indicatorsEnabled = merged?.validation?.fileTreeIndicators !== false;
+ // Doc count for the on-open budget, read off the list the file tree already
+ // loaded — so deciding whether to audit never costs a walk of its own. Optional
+ // like the Problems panel's own use: absent provider (bare harness) reads as
+ // "count unknown", which holds the on-open audit rather than guessing.
+ const pageCount = useOptionalPageList()?.pages.size ?? 0;
+ // Latches the once-per-open audit. A ref, not state: flipping it must not
+ // re-render, and the page list keeps growing as docs are created.
+ const ranOnOpenRef = useRef(false);
useEffect(() => {
if (!indicatorsEnabled) return;
@@ -44,8 +141,9 @@ export function ValidationFreshness() {
const revalidate = (docName: string) => {
void runValidationAudit({ kind: 'doc', docName }).then((result) => {
// A failed scoped audit (server hiccup) keeps the previous entry —
- // stale beats wrongly-clean.
- if (disposed || result === null) return;
+ // stale beats wrongly-clean. A superseded one keeps it for the same
+ // reason: the config change that superseded it re-runs the whole plane.
+ if (disposed || result === null || result === AUDIT_SUPERSEDED) return;
const diagnostics = result.files
.filter((file) => filePathToDocName(file.file) === docName)
.flatMap((file) => file.diagnostics);
@@ -74,5 +172,94 @@ export function ValidationFreshness() {
};
}, [indicatorsEnabled]);
+ // Trigger 4: re-audit the whole plane when the config or the branch changes.
+ useEffect(() => {
+ if (!indicatorsEnabled) return;
+ let timer: ReturnType<typeof setTimeout> | null = null;
+ // Single-flight: a later invalidation landing mid-walk aborts the walk in
+ // progress, whose result is already stale, rather than racing it to the
+ // store (last writer would otherwise win by arrival order, not recency).
+ // Shared across both signals, so the two classes of invalidation order
+ // against each other rather than only against themselves.
+ let inFlight: AbortController | null = null;
+
+ const runAudit = () => {
+ inFlight?.abort();
+ const controller = new AbortController();
+ inFlight = controller;
+ void auditProjectIntoStore(controller.signal).finally(() => {
+ if (inFlight === controller) inFlight = null;
+ });
+ };
+
+ const schedule = () => {
+ if (timer !== null) clearTimeout(timer);
+ timer = setTimeout(() => {
+ timer = null;
+ runAudit();
+ }, PLANE_AUDIT_DEBOUNCE_MS);
+ };
+
+ // Branch-changed fires only on an actual change — the first observation of a
+ // branch seeds the pool without emitting — so subscribing here costs no walk
+ // at boot; the on-open trigger owns that one.
+ const unsubscribers = [
+ subscribeToLintConfigChanged(schedule),
+ subscribeToBranchChanged(schedule),
+ ];
+
+ return () => {
+ for (const unsubscribe of unsubscribers) unsubscribe();
+ if (timer !== null) clearTimeout(timer);
+ inFlight?.abort();
+ };
+ }, [indicatorsEnabled]);
+
+ // Trigger 5: one audit per project open, at any project size.
+ useEffect(() => {
+ if (!indicatorsEnabled) return;
+ // The page list arrives asynchronously; a count of 0 means "not known yet",
+ // not "empty project", so wait rather than auditing against nothing. The
+ // count is a readiness + retry signal only — it does NOT gate on size.
+ if (pageCount === 0 || ranOnOpenRef.current) return;
+ const controller = new AbortController();
+ let timer: ReturnType<typeof setTimeout> | null = null;
+ let failures = 0;
+
+ const attempt = () => {
+ timer = null;
+ // Latch only once a run actually populates the store — never at schedule
+ // time. `pageCount` is in the deps, so a doc count that shifts during the
+ // settle delay (an optimistic add, a background refetch) tears this effect
+ // down and aborts the run. Latching before the run would leave the
+ // early-return above refusing to reschedule, stranding the sidebar empty
+ // for the session.
+ void auditProjectIntoStore(controller.signal).then((wrote) => {
+ if (wrote) {
+ ranOnOpenRef.current = true;
+ return;
+ }
+ // Teardown, not failure: the effect is gone and rescheduling onto it
+ // would outlive its own cleanup.
+ if (controller.signal.aborted) return;
+ failures += 1;
+ if (failures >= AUDIT_ON_OPEN_MAX_ATTEMPTS) {
+ // Each attempt logs its own transport failure, but nothing marks the
+ // point where the plane is abandoned for the session — leaving a bare
+ // sidebar that looks identical to one nothing ever tried to fill.
+ console.warn('[audit] on-open audit exhausted retries; file-tree counts unavailable');
+ return;
+ }
+ timer = setTimeout(attempt, AUDIT_ON_OPEN_RETRY_MS * 2 ** (failures - 1));
+ });
+ };
+
+ timer = setTimeout(attempt, AUDIT_ON_OPEN_DELAY_MS);
+ return () => {
+ if (timer !== null) clearTimeout(timer);
+ controller.abort();
+ };
+ }, [indicatorsEnabled, pageCount]);
+
return null;
}
diff --git a/packages/app/src/editor/validation-audit-client.ts b/packages/app/src/editor/validation-audit-client.ts
index 2b673d18a..0d1690011 100644
--- a/packages/app/src/editor/validation-audit-client.ts
+++ b/packages/app/src/editor/validation-audit-client.ts
@@ -7,11 +7,14 @@
*/
import {
+ type ValidationAuditCountsResponse,
+ ValidationAuditCountsResponseSchema,
type ValidationAuditResponse,
ValidationAuditResponseSchema,
type ValidationDocResult,
} from '@inkeep/open-knowledge-core';
import { useEffect, useState } from 'react';
+import type { z } from 'zod';
import { subscribeToDocumentsChanged } from '@/lib/documents-events';
/** Wire-loose diagnostic (schema `source` is any string, by design). */
@@ -23,30 +26,80 @@ export type AuditScope =
/** Extension-less docName — the server resolves the on-disk extension. */
| { kind: 'doc'; docName: string };
+/**
+ * A walk the server abandoned because the lint config moved under it. Not a
+ * failure: whatever changed the config also schedules the replacement walk, so
+ * a caller should leave its current state alone rather than surface an error.
+ */
+export const AUDIT_SUPERSEDED = 'audit-superseded' as const;
+
/**
* GET the unified audit plane for a scope. Returns every in-scope doc that has
* at least one diagnostic from any validator, plus rollup counts and engine
- * degradation warnings. null on any failure.
+ * degradation warnings. null on failure, `AUDIT_SUPERSEDED` when the config
+ * moved under the walk.
*/
export async function runValidationAudit(
scope: AuditScope = { kind: 'project' },
-): Promise<ValidationAuditResponse | null> {
+): Promise<ValidationAuditResponse | null | typeof AUDIT_SUPERSEDED> {
+ return fetchAudit(scope, ValidationAuditResponseSchema, false);
+}
+
+/**
+ * The same audit, tallied instead of enumerated — per-file error/warning counts
+ * split by validator source, with no messages, ranges, or fix edits. The
+ * freshness path behind file-tree tints wants exactly these counts; on a large
+ * KB the enumerated plane is tens of MB it would discard on arrival.
+ *
+ * `signal` aborts a run whose result is already superseded (a second config
+ * change landing while the first walk is still going).
+ */
+export async function runValidationAuditCounts(
+ scope: AuditScope = { kind: 'project' },
+ signal?: AbortSignal,
+): Promise<ValidationAuditCountsResponse | null | typeof AUDIT_SUPERSEDED> {
+ return fetchAudit(scope, ValidationAuditCountsResponseSchema, true, signal);
+}
+
+/** Shared fetch + parse for both audit planes; they differ only in shape. */
+async function fetchAudit<T>(
+ scope: AuditScope,
+ schema: z.ZodType<T>,
+ counts: boolean,
+ signal?: AbortSignal,
+): Promise<T | null | typeof AUDIT_SUPERSEDED> {
try {
- const query =
- scope.kind === 'path'
- ? `?path=${encodeURIComponent(scope.path)}`
- : scope.kind === 'doc'
- ? `?doc=${encodeURIComponent(scope.docName)}`
- : '';
- const res = await fetch(`/api/audit${query}`);
+ const params = new URLSearchParams();
+ if (scope.kind === 'path') params.set('path', scope.path);
+ else if (scope.kind === 'doc') params.set('doc', scope.docName);
+ if (counts) params.set('counts', '1');
+ const query = params.size === 0 ? '' : `?${params}`;
+ const res = await fetch(`/api/audit${query}`, signal === undefined ? undefined : { signal });
if (!res.ok) {
+ // The audit routes reserve 409 for a walk the config moved under, which is
+ // the expected outcome of toggling a rule mid-walk. Reporting it as a
+ // failure would strand the Problems panel, so it gets its own signal.
+ if (res.status === 409) return AUDIT_SUPERSEDED;
// Log like the schema-drift path below: a non-OK response (server down,
// port conflict) otherwise silently leaves the panel + tree on stale data.
console.warn('[audit] request failed', res.status, res.statusText);
return null;
}
- const body = await res.json().catch(() => null);
- const parsed = ValidationAuditResponseSchema.safeParse(body);
+ let body: unknown;
+ try {
+ body = await res.json();
+ } catch {
+ // The body read is a second cancellation point: a signal that fires after
+ // the response resolves rejects here rather than at the fetch, so an
+ // abort would otherwise be reported as a malformed body.
+ if (signal?.aborted === true) return null;
+ // A body that isn't JSON at all (proxy HTML error page, truncated
+ // response, charset mismatch) is a transport failure, not a contract
+ // drift — log it distinctly so triage doesn't chase a phantom schema miss.
+ console.warn('[audit] response body is not valid JSON');
+ return null;
+ }
+ const parsed = schema.safeParse(body);
if (!parsed.success) {
// Mirror the sibling lint-config-client logging so a client/server
// schema drift window leaves a diagnostic trail instead of a silent null.
@@ -55,6 +108,11 @@ export async function runValidationAudit(
}
return parsed.data;
} catch (err) {
+ // An abort is the caller superseding its own request, not a failure —
+ // logging it would cry wolf on every rapid second toggle. Keyed on the
+ // signal rather than the error shape because abort(reason) rejects with
+ // that reason verbatim, so a custom reason never arrives as an AbortError.
+ if (signal?.aborted === true) return null;
console.warn('[audit] fetch threw', err);
return null;
}
@@ -86,7 +144,7 @@ export function useDocLinkFindings(docName: string | null): WireDiagnostic[] {
let cancelled = false;
const load = () => {
void runValidationAudit({ kind: 'doc', docName }).then((result) => {
- if (cancelled || result === null) return;
+ if (cancelled || result === null || result === AUDIT_SUPERSEDED) return;
const linkFindings = result.files
.flatMap((f) => f.diagnostics)
.filter((d) => d.source === 'links');
diff --git a/packages/app/src/lib/validation-store.test.ts b/packages/app/src/lib/validation-store.test.ts
index 35b0f9735..d70408e95 100644
--- a/packages/app/src/lib/validation-store.test.ts
+++ b/packages/app/src/lib/validation-store.test.ts
@@ -10,6 +10,7 @@ import {
patchDocValidationFromAudit,
patchDocValidationSource,
replaceValidationFromAudit,
+ replaceValidationFromCounts,
resetValidationStoreForTest,
subscribeToValidationStore,
} from './validation-store';
@@ -84,4 +85,56 @@ describe('validation store', () => {
patchDocValidationSource('clean', 'lint', { errorCount: 0, warningCount: 0 });
expect(getValidationSnapshot().has('clean')).toBe(false);
});
+
+ test('replaceValidationFromCounts merges per-source tallies from the counts plane', () => {
+ replaceValidationFromCounts([
+ {
+ file: 'guides/setup.md',
+ lint: { errorCount: 2, warningCount: 1 },
+ links: { errorCount: 0, warningCount: 3 },
+ },
+ {
+ file: 'clean.md',
+ lint: { errorCount: 0, warningCount: 0 },
+ links: { errorCount: 0, warningCount: 0 },
+ },
+ ]);
+ const snapshot = getValidationSnapshot();
+ // Keyed by extension-less docName, same as the enumerated plane.
+ expect(snapshot.get('guides/setup')).toEqual({ errorCount: 2, warningCount: 4 });
+ // A doc the audit reported with no problems is absent, not present-at-zero.
+ expect(snapshot.has('clean.md')).toBe(false);
+ expect(snapshot.has('clean')).toBe(false);
+ });
+
+ test('replaceValidationFromCounts is full-plane truth — healed docs drop out', () => {
+ patchDocValidationFromAudit('gone', [lintError]);
+ expect(getValidationSnapshot().has('gone')).toBe(true);
+
+ replaceValidationFromCounts([
+ {
+ file: 'other.md',
+ lint: { errorCount: 1, warningCount: 0 },
+ links: { errorCount: 0, warningCount: 0 },
+ },
+ ]);
+ expect(getValidationSnapshot().has('gone')).toBe(false);
+ expect(getValidationSnapshot().has('other')).toBe(true);
+ });
+
+ test('the counts plane and the enumerated plane agree for the same doc', () => {
+ // The two triggers must never disagree about one doc's totals; both route
+ // their bucketing through the shared core predicate.
+ replaceValidationFromAudit([{ file: 'a.md', diagnostics: [lintError, lintWarning, deadLink] }]);
+ const fromDiagnostics = getValidationSnapshot().get('a');
+
+ replaceValidationFromCounts([
+ {
+ file: 'a.md',
+ lint: { errorCount: 1, warningCount: 1 },
+ links: { errorCount: 1, warningCount: 0 },
+ },
+ ]);
+ expect(getValidationSnapshot().get('a')).toEqual(fromDiagnostics);
+ });
});
diff --git a/packages/app/src/lib/validation-store.ts b/packages/app/src/lib/validation-store.ts
index 3e05111f2..38092b9e2 100644
--- a/packages/app/src/lib/validation-store.ts
+++ b/packages/app/src/lib/validation-store.ts
@@ -5,24 +5,36 @@
* `useSyncExternalStore`-compatible) rather than React context — the file
* tree consumes it from a MutationObserver callback outside React.
*
- * Counts are tracked per validator source so the three freshness triggers can
- * write independently without clobbering each other:
+ * Counts are tracked per validator source so the freshness triggers can write
+ * independently without clobbering each other:
* 1. a project audit replaces the WHOLE store (both sources, every doc);
* 2. the open doc's lint entry is written live off the `useDocDiagnostics`
* debounce, and its links entry off the doc-scoped audit fetch;
* 3. a persisted doc (CC1 `disk-ack`, the one per-doc channel) is re-validated
- * alone and patched (both sources).
- * Never a background whole-project walk.
+ * alone and patched (both sources);
+ * 4. a lint-config change (plugin enabled, rule toggled, schema edited)
+ * replaces the whole store from the counts-only audit plane — the config
+ * that produced every existing entry no longer holds;
+ * 5. opening the project replaces the whole store once, so a KB configured in
+ * an earlier session is correct on arrival instead of empty until the user
+ * opens files or audits by hand (no project-size cap — the on-demand and
+ * config-change audits have none either).
+ * No trigger polls. The two whole-project walks (4 and 5) fetch counts only,
+ * single-flight, and coalesce server-side.
*/
+import {
+ countDiagnosticsBySource,
+ type ValidationDocCounts,
+ type ValidationSourceCounts,
+ type ValidationSourceKey,
+} from '@inkeep/open-knowledge-core';
import { filePathToDocName } from '@/lib/doc-hash';
-export interface DocProblemCounts {
- errorCount: number;
- warningCount: number;
-}
+/** Alias kept for existing call sites; the shape lives in core with the predicate. */
+export type DocProblemCounts = ValidationSourceCounts;
-export type ValidationSourceKey = 'lint' | 'links';
+export type { ValidationSourceKey };
interface DiagnosticShape {
severity: string;
@@ -58,19 +70,14 @@ function rebuildSnapshotAndNotify(): void {
for (const listener of listeners) listener();
}
-/** Split one doc's diagnostics into per-source counts ('links' vs everything else). */
-function countBySource(diagnostics: readonly DiagnosticShape[]): SourceCounts {
- const counts: SourceCounts = {
- lint: { errorCount: 0, warningCount: 0 },
- links: { errorCount: 0, warningCount: 0 },
- };
- for (const diagnostic of diagnostics) {
- const bucket = diagnostic.source === 'links' ? counts.links : counts.lint;
- if (diagnostic.severity === 'error') bucket.errorCount += 1;
- else bucket.warningCount += 1;
- }
- return counts;
-}
+/**
+ * Split one doc's diagnostics into per-source counts. This is the SAME core
+ * predicate the server tallies its counts-only audit plane with, so an entry
+ * written from the enumerated plane and one written from the counts plane can
+ * never disagree about the same doc.
+ */
+const countBySource: (diagnostics: readonly DiagnosticShape[]) => SourceCounts =
+ countDiagnosticsBySource;
export function subscribeToValidationStore(listener: () => void): () => void {
listeners.add(listener);
@@ -98,6 +105,20 @@ export function replaceValidationFromAudit(
rebuildSnapshotAndNotify();
}
+/**
+ * Trigger 4 — a counts-only project audit, same full-plane truth as trigger 1
+ * but tallied server-side. Entries are already split by source, so nothing is
+ * re-derived here; docs healed since the last audit drop out as they do for
+ * trigger 1.
+ */
+export function replaceValidationFromCounts(files: readonly ValidationDocCounts[]): void {
+ entries.clear();
+ for (const file of files) {
+ entries.set(filePathToDocName(file.file), { lint: file.lint, links: file.links });
+ }
+ rebuildSnapshotAndNotify();
+}
+
/**
* Trigger 3 — one doc re-validated (scoped audit): both sources for that doc
* are fresh truth; an empty plane means the doc healed.
diff --git a/packages/app/tests/integration/audit-branch-generation.test.ts b/packages/app/tests/integration/audit-branch-generation.test.ts
new file mode 100644
index 000000000..0bf45b558
--- /dev/null
+++ b/packages/app/tests/integration/audit-branch-generation.test.ts
@@ -0,0 +1,139 @@
+/**
+ * The audit surface (`GET /api/audit`) against a branch switch that lands while
+ * a walk is in flight.
+ *
+ * A switch replaces the content set wholesale on disk while moving nothing in
+ * the lint configuration, so the audit's coalescing key only moves if it
+ * carries the active branch alongside the lint-config epoch. Without the branch
+ * dimension an audit issued after the switch computes an identical key,
+ * attaches to the walk started before it, and is served the previous branch's
+ * plane — and the pre-switch walk itself publishes a plane whose early docs are
+ * the old branch's bytes and whose later docs are the new branch's.
+ *
+ * The switch is driven through the server's own branch state
+ * (`switchReconciledBaseScope`, the call the HEAD watcher makes) paired with the
+ * disk-side content swap, rather than through real git: the harness boots with
+ * `gitEnabled: false`, so no HEAD watcher exists to observe a checkout.
+ *
+ * Own server (not the shared one in `audit-http.test.ts`): the corpus is
+ * rewritten in place mid-test, which any other test sharing the tree would see.
+ */
+
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ValidationAuditResponseSchema } from '@inkeep/open-knowledge-core';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import { createTestServer, type TestServer } from './test-harness.ts';
+
+let server: TestServer;
+
+beforeAll(async () => {
+ server = await createTestServer({ markdownlintEnabled: true });
+}, HARNESS_BOOT_TIMEOUT_MS);
+
+afterAll(async () => {
+ await server.cleanup();
+});
+
+const SCOPE = 'audit-branch';
+
+/**
+ * Sized so the whole-scope walk runs about a second — long enough that the
+ * switch lands mid-walk, and few enough files that seeding and file-watcher
+ * indexing stay cheap. In the pre-switch corpus every line carries a hard tab,
+ * so MD010 separates the two branches' content.
+ */
+const DOC_COUNT = 60;
+const LINE_COUNT = 800;
+
+const TEST_TIMEOUT_MS = 120_000;
+
+function api(pathAndQuery: string): string {
+ return `http://127.0.0.1:${server.port}${pathAndQuery}`;
+}
+
+function writeCorpus(folder: string, separator: '\t' | ' '): void {
+ const lines = ['# Title', ''];
+ for (let i = 0; i < LINE_COUNT; i += 1) {
+ lines.push(`Paragraph ${i} with${separator}a hard tab and some filler text.`, '');
+ }
+ const text = lines.join('\n');
+ mkdirSync(folder, { recursive: true });
+ for (let i = 0; i < DOC_COUNT; i += 1) {
+ writeFileSync(join(folder, `doc-${i}.md`), text, 'utf-8');
+ }
+}
+
+async function auditScope(): Promise<Response> {
+ return fetch(api(`/api/audit?path=${SCOPE}`));
+}
+
+function parseAudit(body: unknown): { md010: number; fileCount: number } {
+ const parsed = ValidationAuditResponseSchema.parse(body);
+ return {
+ md010: parsed.files.flatMap((f) => f.diagnostics).filter((d) => d.code === 'MD010').length,
+ fileCount: parsed.fileCount,
+ };
+}
+
+describe('GET /api/audit across a branch switch', () => {
+ test(
+ 'an audit issued after a branch switch is never served the pre-switch plane',
+ async () => {
+ const folder = join(server.contentDir, SCOPE);
+ writeCorpus(folder, '\t');
+ try {
+ // The tabs are live to begin with, so a post-switch plane that still
+ // carries MD010 is a stale answer and not a mis-seeded fixture. Scoped
+ // to one doc on purpose: a whole-scope pre-check would warm the audit's
+ // per-file cache and leave the walk below too short to still be running
+ // when the switch lands.
+ const before = await fetch(api(`/api/audit?path=${SCOPE}%2Fdoc-0.md`));
+ expect(before.status).toBe(200);
+ expect(parseAudit(await before.json()).md010).toBeGreaterThan(0);
+
+ let firstSettled = false;
+ const first = auditScope().then((res) => {
+ firstSettled = true;
+ return res;
+ });
+
+ // A real round-trip the server can only answer once the walk has
+ // yielded — the interleave point, with no sleep.
+ expect((await fetch(api('/api/lint/config'))).status).toBe(200);
+
+ // The two halves of a checkout, in the order git performs them: the
+ // working tree is swapped, then the server's branch state follows.
+ writeCorpus(folder, ' ');
+ const { durabilityState } = server.instance;
+ expect(durabilityState.getActiveBranch()).not.toBe('audit-branch-target');
+ durabilityState.switchReconciledBaseScope('audit-branch-target');
+
+ // The property under test only exists while the earlier walk is still
+ // running; a failure here means the corpus stopped being big enough,
+ // not that the behavior changed.
+ expect(firstSettled).toBe(false);
+
+ const after = await auditScope();
+ expect(after.status).toBe(200);
+ const afterPlane = parseAudit(await after.json());
+ // A walk that found nothing would also report zero MD010 — pin that it
+ // actually re-read the scope.
+ expect(afterPlane.fileCount).toBe(DOC_COUNT);
+ expect(afterPlane.md010).toBe(0);
+
+ // The superseded walk reports no plane rather than a mixed one: its
+ // early docs read the pre-switch bytes and its later docs would not
+ // have.
+ const firstRes = await first;
+ expect(firstRes.status).toBe(409);
+ const problem = (await firstRes.json()) as { type?: string };
+ expect(problem.type).toBe('urn:ok:error:audit-superseded');
+ } finally {
+ rmSync(folder, { recursive: true, force: true });
+ }
+ },
+ TEST_TIMEOUT_MS,
+ );
+});
diff --git a/packages/app/tests/integration/audit-config-epoch.test.ts b/packages/app/tests/integration/audit-config-epoch.test.ts
new file mode 100644
index 000000000..008bee190
--- /dev/null
+++ b/packages/app/tests/integration/audit-config-epoch.test.ts
@@ -0,0 +1,124 @@
+/**
+ * The audit surface (`GET /api/audit`) against a rule toggle that lands while a
+ * walk is in flight.
+ *
+ * A native markdownlint rule write moves no base-config fingerprint — the rules
+ * come from the `.markdownlint.*` cascade — so the audit's coalescing key only
+ * moves if it carries a lint-config epoch. Without one, an audit issued after
+ * the toggle attaches to the walk started before it and is served counts
+ * computed under the rules the user just changed.
+ *
+ * Own server (not the shared one in `audit-http.test.ts`): the rule write puts
+ * a governing `.markdownlint.json` at the content root, which replaces the
+ * project's rules for every doc in the tree while it exists.
+ */
+
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ValidationAuditResponseSchema } from '@inkeep/open-knowledge-core';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import { createTestServer, type TestServer } from './test-harness.ts';
+
+let server: TestServer;
+
+beforeAll(async () => {
+ server = await createTestServer({ markdownlintEnabled: true });
+}, HARNESS_BOOT_TIMEOUT_MS);
+
+afterAll(async () => {
+ await server.cleanup();
+});
+
+const SCOPE = 'audit-epoch';
+
+/**
+ * Sized so the whole-scope walk runs about a second — long enough that a rule
+ * write issued right after the walk starts is serviced mid-walk, and few enough
+ * files that seeding and file-watcher indexing stay cheap. Every line carries a
+ * hard tab, so MD010 is the rule under test.
+ */
+const DOC_COUNT = 60;
+const LINE_COUNT = 800;
+
+const TEST_TIMEOUT_MS = 120_000;
+
+function api(pathAndQuery: string): string {
+ return `http://127.0.0.1:${server.port}${pathAndQuery}`;
+}
+
+function seedTabbedCorpus(folder: string): void {
+ const lines = ['# Title', ''];
+ for (let i = 0; i < LINE_COUNT; i += 1) {
+ lines.push(`Paragraph ${i} with\ta hard tab and some filler text.`, '');
+ }
+ const text = lines.join('\n');
+ mkdirSync(folder, { recursive: true });
+ for (let i = 0; i < DOC_COUNT; i += 1) {
+ writeFileSync(join(folder, `doc-${i}.md`), text, 'utf-8');
+ }
+}
+
+async function auditScope(): Promise<Response> {
+ return fetch(api(`/api/audit?path=${SCOPE}`));
+}
+
+function md010Count(body: unknown): number {
+ const parsed = ValidationAuditResponseSchema.parse(body);
+ return parsed.files.flatMap((f) => f.diagnostics).filter((d) => d.code === 'MD010').length;
+}
+
+describe('GET /api/audit across a lint-config change', () => {
+ test(
+ 'an audit issued after a rule write is never served the pre-write plane',
+ async () => {
+ const folder = join(server.contentDir, SCOPE);
+ const nativeFile = join(server.contentDir, '.markdownlint.json');
+ seedTabbedCorpus(folder);
+ try {
+ // The rule is live to begin with, so a post-toggle plane that still
+ // carries MD010 is a stale answer and not a mis-seeded fixture. Scoped
+ // to one doc on purpose: a whole-scope pre-check would warm the audit's
+ // per-file cache and leave the walk below too short to still be running
+ // when the rule write lands.
+ const before = await fetch(api(`/api/audit?path=${SCOPE}%2Fdoc-0.md`));
+ expect(before.status).toBe(200);
+ expect(md010Count(await before.json())).toBeGreaterThan(0);
+
+ let firstSettled = false;
+ const first = auditScope().then((res) => {
+ firstSettled = true;
+ return res;
+ });
+
+ // Serviced mid-walk — which is only possible because the walk yields.
+ // No sleep: awaiting this response IS the interleave point.
+ const write = await fetch(api('/api/lint/markdownlint-config'), {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ ruleId: 'MD010', value: false }),
+ });
+ expect(write.status).toBe(200);
+ // The property under test only exists while the earlier walk is still
+ // running; a failure here means the corpus stopped being big enough,
+ // not that the behavior changed.
+ expect(firstSettled).toBe(false);
+
+ const after = await auditScope();
+ expect(after.status).toBe(200);
+ expect(md010Count(await after.json())).toBe(0);
+
+ // The superseded walk reports no plane rather than a mixed one: its
+ // early docs saw MD010 enabled and its later docs would not have.
+ const firstRes = await first;
+ expect(firstRes.status).toBe(409);
+ const problem = (await firstRes.json()) as { type?: string };
+ expect(problem.type).toBe('urn:ok:error:audit-superseded');
+ } finally {
+ rmSync(folder, { recursive: true, force: true });
+ rmSync(nativeFile, { force: true });
+ }
+ },
+ TEST_TIMEOUT_MS,
+ );
+});
diff --git a/packages/app/tests/integration/audit-http.test.ts b/packages/app/tests/integration/audit-http.test.ts
index b67742f6b..fec58c2c6 100644
--- a/packages/app/tests/integration/audit-http.test.ts
+++ b/packages/app/tests/integration/audit-http.test.ts
@@ -11,6 +11,8 @@
import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import {
+ type ValidationAuditCountsResponse,
+ ValidationAuditCountsResponseSchema,
type ValidationAuditResponse,
ValidationAuditResponseSchema,
} from '@inkeep/open-knowledge-core';
@@ -179,4 +181,79 @@ describe('GET /api/audit', () => {
const both = await fetch(api('/api/audit?doc=a&path=b.md'));
expect(both.status).toBe(400);
});
+
+ test(
+ 'counts=1 returns the same plane tallied per file and per source',
+ async () => {
+ const folder = join(server.contentDir, 'audit-counts');
+ mkdirSync(folder, { recursive: true });
+ writeFileSync(join(folder, 'tabbed.md'), TABBED_BODY, 'utf-8');
+ try {
+ const enumeratedRes = await fetch(api('/api/audit?path=audit-counts'));
+ const countsRes = await fetch(api('/api/audit?path=audit-counts&counts=1'));
+ expect(enumeratedRes.status).toBe(200);
+ expect(countsRes.status).toBe(200);
+
+ const enumerated = ValidationAuditResponseSchema.parse(
+ await enumeratedRes.json(),
+ ) satisfies ValidationAuditResponse;
+ const counts = ValidationAuditCountsResponseSchema.parse(
+ await countsRes.json(),
+ ) satisfies ValidationAuditCountsResponse;
+
+ // Same files, same rollups — the counts plane is a derivation, not a
+ // second determination.
+ expect(counts.files.map((f) => f.file)).toEqual(enumerated.files.map((f) => f.file));
+ expect(counts.errorCount).toBe(enumerated.errorCount);
+ expect(counts.warningCount).toBe(enumerated.warningCount);
+ expect(counts.fileCount).toBe(enumerated.fileCount);
+
+ const tabbed = counts.files.find((f) => f.file.endsWith('tabbed.md'));
+ expect(tabbed).toBeDefined();
+ expect(tabbed?.lint.warningCount).toBeGreaterThan(0);
+ // The tallies carry no diagnostic bodies — that is the whole point of
+ // the mode, and the wire schema is strict about the file shape.
+ expect(Object.keys(tabbed ?? {}).sort()).toEqual(['file', 'links', 'lint']);
+ } finally {
+ rmSync(folder, { recursive: true, force: true });
+ }
+ },
+ HARNESS_BOOT_TIMEOUT_MS,
+ );
+
+ test(
+ 'concurrent identical audits are coalesced and agree',
+ async () => {
+ const folder = join(server.contentDir, 'audit-coalesce');
+ mkdirSync(folder, { recursive: true });
+ writeFileSync(join(folder, 'tabbed.md'), TABBED_BODY, 'utf-8');
+ try {
+ // Several windows firing the same freshness pass at once, plus a panel
+ // refresh: all in flight together, all must resolve to one truth.
+ const responses = await Promise.all([
+ fetch(api('/api/audit?path=audit-coalesce&counts=1')),
+ fetch(api('/api/audit?path=audit-coalesce&counts=1')),
+ fetch(api('/api/audit?path=audit-coalesce&counts=1')),
+ fetch(api('/api/audit?path=audit-coalesce')),
+ ]);
+ for (const response of responses) expect(response.status).toBe(200);
+
+ const bodies = await Promise.all(responses.map((r) => r.json()));
+ const countsBodies = bodies
+ .slice(0, 3)
+ .map((body) => ValidationAuditCountsResponseSchema.parse(body));
+ expect(countsBodies[1]).toEqual(countsBodies[0]);
+ expect(countsBodies[2]).toEqual(countsBodies[0]);
+
+ // The enumerated joiner shares the same underlying walk, so its rollups
+ // must match the tallied ones rather than reflecting a separate pass.
+ const enumerated = ValidationAuditResponseSchema.parse(bodies[3]);
+ expect(enumerated.errorCount).toBe(countsBodies[0]?.errorCount);
+ expect(enumerated.warningCount).toBe(countsBodies[0]?.warningCount);
+ } finally {
+ rmSync(folder, { recursive: true, force: true });
+ }
+ },
+ HARNESS_BOOT_TIMEOUT_MS,
+ );
});
diff --git a/packages/app/tests/stress/unified-problems.e2e.ts b/packages/app/tests/stress/unified-problems.e2e.ts
index e0ba43756..f6388f84f 100644
--- a/packages/app/tests/stress/unified-problems.e2e.ts
+++ b/packages/app/tests/stress/unified-problems.e2e.ts
@@ -5,13 +5,19 @@
* problem rows inside the real `@pierre/trees` shadow root — the rung jsdom
* structurally cannot cover (unsafeCSS paints only in a browser).
*
- * Freshness trigger 3 (an agent write to an UNOPENED doc tints its tree row
- * via the CC1 disk-ack relay, no project audit involved) is exercised against
- * the live persistence pipeline.
+ * Three freshness triggers are exercised against the live persistence pipeline,
+ * the real rule-write endpoint, and the real Settings switches — each asserting
+ * on an UNOPENED doc's row, because "correct without opening each file" is the
+ * behavior at issue:
+ * - trigger 3: an agent write tints via the CC1 disk-ack relay, no audit;
+ * - trigger 4: enabling a plugin (markdownlint AND frontmatter) or toggling a
+ * rule off re-audits, so rows update without being reopened;
+ * - trigger 5: a doc whose problems predate the page load tints on open, with
+ * nothing in the session touched at all.
*/
import { randomUUID } from 'node:crypto';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import type { Page } from '@playwright/test';
import {
@@ -167,10 +173,210 @@ test.describe('unified Problems — file-tree indicators', () => {
expect(colors.problem).not.toBe(colors.clean);
});
- test('an agent write to an unopened doc tints its row via disk-ack, no audit run', async ({
+ test('enabling the plugin from Settings lights up an UNOPENED doc row', async ({ page, api }) => {
+ // The report's headline symptom: "you enable the plugin, nothing lights up."
+ // Driven through the real Settings switch rather than an API call, because
+ // the plugin toggle takes a DIFFERENT route to the freshness trigger than a
+ // rule write does — it patches the project config doc and relies on the
+ // server's CC1 lint-config broadcast after that doc persists, with no local
+ // emitLintConfigChanged() of its own.
+ const suffix = randomUUID().slice(0, 8);
+ const enableDoc = `uv-enable-${suffix}`;
+ await api.createPage(`${enableDoc}.md`);
+ await api.replaceDoc(enableDoc, HARD_TAB_BODY);
+
+ const problemAttr = async () => {
+ const row = await treeRowHandle(page, `${enableDoc}.md`);
+ return row.evaluate((el) => el?.getAttribute('data-ok-problem') ?? null);
+ };
+
+ await expect.poll(problemAttr, { timeout: 30_000 }).toBe('warning');
+
+ // The same deep link the Problems panel's "Enable plugins" pointer uses.
+ await page.goto('/#settings/plugins-manage');
+ await expect(page.getByTestId('settings-plugins-manage')).toBeVisible({ timeout: 10_000 });
+ const toggle = page.getByTestId('settings-plugin-toggle-markdownlint');
+ await expect(toggle).toBeVisible({ timeout: 10_000 });
+
+ // Off: the doc's only finding was MD010, so its row must go bare.
+ await toggle.click();
+ await expect.poll(problemAttr, { timeout: 30_000 }).toBeNull();
+
+ // Back on — the reported scenario. The row must light up again with the doc
+ // still never opened. Left ON so the file's config state matches beforeEach.
+ await toggle.click();
+ await expect.poll(problemAttr, { timeout: 30_000 }).toBe('warning');
+ });
+
+ test('enabling the frontmatter plugin lights up an UNOPENED doc with a schema violation', async ({
+ page,
+ api,
+ workerServer,
+ }) => {
+ // The report's FIRST symptom names frontmatter specifically ("files with
+ // frontmatter issues don't turn yellow until you click into them one at a
+ // time"). markdownlint and frontmatter are separate plugins reaching the
+ // audit plane by different validators, so covering one does not cover the
+ // other.
+ const suffix = randomUUID().slice(0, 8);
+ const fmDoc = `uv-fm-${suffix}`;
+ const schemaRel = join('.ok', 'schemas', `uv-fm-${suffix}.schema.json`);
+ mkdirSync(join(workerServer.contentDir, '.ok', 'schemas'), { recursive: true });
+ writeFileSync(
+ join(workerServer.contentDir, schemaRel),
+ JSON.stringify({
+ $schema: 'http://json-schema.org/draft-07/schema#',
+ type: 'object',
+ required: ['title'],
+ }),
+ 'utf-8',
+ );
+ // The schema is mapped but the PLUGIN starts off, so nothing validates yet —
+ // the state a user is in right before they flip the switch.
+ writeFileSync(
+ join(workerServer.contentDir, '.ok', 'config.yml'),
+ [
+ 'contentRules:',
+ ' markdownlint:',
+ ' enabled: true',
+ ' frontmatter:',
+ ' enabled: false',
+ ' schemas:',
+ ` - file: ${schemaRel}`,
+ ` appliesTo: '${fmDoc}'`,
+ ' enabled: true',
+ '',
+ ].join('\n'),
+ 'utf-8',
+ );
+
+ // Frontmatter present but missing the required `title`, and no hard tab, so
+ // the ONLY possible finding is the frontmatter one.
+ await api.createPage(`${fmDoc}.md`);
+ await api.replaceDoc(fmDoc, '---\nsummary: no title here\n---\n\n# Body\n\nClean prose.\n');
+
+ const problemAttr = async () => {
+ const row = await treeRowHandle(page, `${fmDoc}.md`);
+ return row.evaluate((el) => el?.getAttribute('data-ok-problem') ?? null);
+ };
+
+ // Plugin off: the row is bare even though the doc violates the schema.
+ await expect.poll(problemAttr, { timeout: 20_000 }).toBeNull();
+
+ await page.goto('/#settings/plugins-manage');
+ await expect(page.getByTestId('settings-plugins-manage')).toBeVisible({ timeout: 10_000 });
+ const toggle = page.getByTestId('settings-plugin-toggle-frontmatter');
+ await expect(toggle).toBeVisible({ timeout: 10_000 });
+ await toggle.click();
+
+ // Enabling the plugin must light the row up with the doc never opened.
+ await expect.poll(problemAttr, { timeout: 30_000 }).toBe('warning');
+
+ // Leave the plugin off again: this test's config write lives in the project
+ // config DOC, which outlives the per-test config.yml that beforeEach lays
+ // down, so a sibling test could otherwise inherit frontmatter validation.
+ // The schema mapping itself goes inert once the plugin is off (the audit
+ // skips schema resolution and appliesTo checks entirely when disabled).
+ await toggle.click();
+ await expect.poll(problemAttr, { timeout: 30_000 }).toBeNull();
+ });
+
+ test('toggling a rule off clears an UNOPENED doc row, no Problems panel interaction', async ({
page,
api,
+ baseURL,
+ workerServer,
}) => {
+ // Freshness trigger 4, the whole reported symptom: validation state used to
+ // stand until each file was reopened, so switching a rule off left its
+ // sidebar tint and count in place. The doc here is never opened and the
+ // Problems panel is never touched — a config change is the only freshness
+ // path available.
+ const suffix = randomUUID().slice(0, 8);
+ const toggleDoc = `uv-toggle-${suffix}`;
+ await api.createPage(`${toggleDoc}.md`);
+ await api.replaceDoc(toggleDoc, HARD_TAB_BODY);
+
+ const problemAttr = async () => {
+ const row = await treeRowHandle(page, `${toggleDoc}.md`);
+ return row.evaluate((el) => el?.getAttribute('data-ok-problem') ?? null);
+ };
+
+ // Baseline via trigger 3 (disk-ack): MD010 is on, so the row tints.
+ await expect.poll(problemAttr, { timeout: 30_000 }).toBe('warning');
+
+ const configPath = join(workerServer.contentDir, '.markdownlint.json');
+ try {
+ // The real rule-write endpoint the Settings rule browser posts to — it
+ // lands on disk AND signals the CC1 lint-config channel, which is how a
+ // window learns about a config change it did not make itself.
+ const res = await fetch(`${baseURL}/api/lint/markdownlint-config`, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({ ruleId: 'MD010', value: false }),
+ });
+ expect(res.ok, 'rule write should succeed').toBe(true);
+
+ // The hard tab is no longer a finding, so the row must go bare on its own.
+ await expect.poll(problemAttr, { timeout: 30_000 }).toBeNull();
+ } finally {
+ // A governing native file applies wholesale, so leaving one behind (even
+ // rule-less) would silence MD010 for every sibling test in this worker.
+ // Discovery re-reads from disk per request, so removing the file restores
+ // OK's tuned defaults for whatever runs next.
+ rmSync(configPath, { force: true });
+ }
+ });
+
+ test('a doc whose problems predate the page load tints on open, nothing touched', async ({
+ page,
+ api,
+ }) => {
+ // Freshness trigger 5. Triggers 2-4 all need something to HAPPEN in the
+ // session, so a project configured in an earlier session used to show a bare
+ // sidebar at every launch until the user opened files or ran the audit by
+ // hand. Reloading is what makes the doc's problems predate the load: the
+ // store is module state, so it starts empty again, and no disk-ack for this
+ // doc will ever reach the new page.
+ const suffix = randomUUID().slice(0, 8);
+ // One doc per validator source: the on-open audit is the whole plane, not a
+ // lint-only pass, so a dead link has to surface the same way a lint finding
+ // does. `links` is the one source the counts plane tracks separately.
+ const priorLintDoc = `uv-prior-lint-${suffix}`;
+ const priorLinkDoc = `uv-prior-link-${suffix}`;
+ await api.createPage(`${priorLintDoc}.md`);
+ await api.createPage(`${priorLinkDoc}.md`);
+ await api.replaceDoc(priorLintDoc, HARD_TAB_BODY);
+ await api.replaceDoc(priorLinkDoc, `# Linker\n\nSee [[uv-prior-ghost-${suffix}]].\n`);
+
+ await page.reload();
+ await waitForProvider(page);
+
+ // No file opened, no Problems panel, no config change, no write after load.
+ const attrOf = async (treePath: string) => {
+ const row = await treeRowHandle(page, treePath);
+ return row.evaluate((el) => el?.getAttribute('data-ok-problem') ?? null);
+ };
+ await expect.poll(() => attrOf(`${priorLintDoc}.md`), { timeout: 30_000 }).toBe('warning');
+ await expect.poll(() => attrOf(`${priorLinkDoc}.md`), { timeout: 30_000 }).toBe('warning');
+ });
+
+ test('an agent write to an unopened doc tints its row via disk-ack', async ({ page, api }) => {
+ // Condition-based wait for the on-open audit (trigger 5) to land, so the tint
+ // asserted below is attributable to the disk-ack path this test is about.
+ // beforeEach seeds lintDocName BEFORE the page loads, so no disk-ack for it
+ // ever reaches this page — its row going warning can only be the on-open
+ // audit, which makes it a signal rather than a sleep.
+ await expect
+ .poll(
+ async () => {
+ const row = await treeRowHandle(page, `${lintDocName}.md`);
+ return row.evaluate((el) => el?.getAttribute('data-ok-problem') ?? null);
+ },
+ { timeout: 30_000 },
+ )
+ .toBe('warning');
+
const suffix = randomUUID().slice(0, 8);
const sleeperDoc = `uv-sleeper-${suffix}`;
await api.createPage(`${sleeperDoc}.md`);
diff --git a/packages/core/src/handoff/urn-ipc-registry.ts b/packages/core/src/handoff/urn-ipc-registry.ts
index c71c8aeb6..b6cbb8bfd 100644
--- a/packages/core/src/handoff/urn-ipc-registry.ts
+++ b/packages/core/src/handoff/urn-ipc-registry.ts
@@ -301,6 +301,10 @@ export const URN_HTTP_ONLY: ReadonlySet<ProblemType> = new Set<ProblemType>([
// native `.markdownlint.*` file can't be written). HTTP-only — the lint
// config surface is REST, with no IPC counterpart.
'urn:ok:error:config-not-writable',
+ // Audit superseded by a concurrent lint-config change (`GET /api/audit`,
+ // `GET /api/lint/audit` → 409). HTTP-only — the audit surface is REST, with
+ // no IPC counterpart.
+ 'urn:ok:error:audit-superseded',
]);
/**
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 9de4d7f63..be222d898 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -517,6 +517,7 @@ export {
type CompiledAppliesTo,
canonicalRuleId,
compileAppliesTo,
+ countDiagnosticsBySource,
DEFAULT_LINKS_VALIDATION,
DEFAULT_LINTER_CONFIG,
DEFAULT_MARKDOWNLINT_CONFIG,
@@ -587,12 +588,20 @@ export {
selectApplicableFrontmatterSchemas,
summarizeAppliesTo,
toEffectiveBase,
+ type ValidationAuditCountsResponse,
+ ValidationAuditCountsResponseSchema,
type ValidationAuditResponse,
ValidationAuditResponseSchema,
+ type ValidationCountsBySource,
type ValidationDiagnostic,
+ type ValidationDocCounts,
+ ValidationDocCountsSchema,
type ValidationDocResult,
ValidationDocResultSchema,
type ValidationSource,
+ type ValidationSourceCounts,
+ type ValidationSourceKey,
+ ZERO_SOURCE_COUNTS,
} from './markdown/lint/index.ts';
export { markdownToHtml, mdastToHtml } from './markdown/mdast-to-html.ts';
export { normalizeDocRelativeAssetUrl } from './markdown/resolve-image-url.ts';
diff --git a/packages/core/src/markdown/lint/config-schemas.ts b/packages/core/src/markdown/lint/config-schemas.ts
index 3162881fc..c94bfce20 100644
--- a/packages/core/src/markdown/lint/config-schemas.ts
+++ b/packages/core/src/markdown/lint/config-schemas.ts
@@ -184,6 +184,28 @@ export const ValidationAuditResponseSchema = z.object({
export type ValidationDocResult = z.infer<typeof ValidationDocResultSchema>;
export type ValidationAuditResponse = z.infer<typeof ValidationAuditResponseSchema>;
+const ValidationSourceCountsSchema = z.object({
+ errorCount: z.number().int().nonnegative(),
+ warningCount: z.number().int().nonnegative(),
+});
+
+export const ValidationDocCountsSchema = z.object({
+ file: z.string(),
+ lint: ValidationSourceCountsSchema,
+ links: ValidationSourceCountsSchema,
+});
+
+export const ValidationAuditCountsResponseSchema = z.object({
+ files: z.array(ValidationDocCountsSchema),
+ fileCount: z.number().int().nonnegative(),
+ errorCount: z.number().int().nonnegative(),
+ warningCount: z.number().int().nonnegative(),
+ warnings: z.array(z.string()),
+});
+
+export type ValidationDocCounts = z.infer<typeof ValidationDocCountsSchema>;
+export type ValidationAuditCountsResponse = z.infer<typeof ValidationAuditCountsResponseSchema>;
+
export const LintFixRequestSchema = z
.object({
docName: safeDocNameField,
diff --git a/packages/core/src/markdown/lint/index.ts b/packages/core/src/markdown/lint/index.ts
index ce0db23a3..00d08265a 100644
--- a/packages/core/src/markdown/lint/index.ts
+++ b/packages/core/src/markdown/lint/index.ts
@@ -55,8 +55,12 @@ export {
MarkdownlintRuleWriteRequestSchema,
type PersistedLinterConfig,
toEffectiveBase,
+ type ValidationAuditCountsResponse,
+ ValidationAuditCountsResponseSchema,
type ValidationAuditResponse,
ValidationAuditResponseSchema,
+ type ValidationDocCounts,
+ ValidationDocCountsSchema,
type ValidationDocResult,
ValidationDocResultSchema,
} from './config-schemas.ts';
@@ -119,3 +123,10 @@ export type {
ValidationSource,
} from './types.ts';
export { DEFAULT_LINKS_VALIDATION, LINKS_VALIDATION_SETTINGS } from './types.ts';
+export {
+ countDiagnosticsBySource,
+ type ValidationCountsBySource,
+ type ValidationSourceCounts,
+ type ValidationSourceKey,
+ ZERO_SOURCE_COUNTS,
+} from './validation-counts.ts';
diff --git a/packages/core/src/markdown/lint/validation-counts.ts b/packages/core/src/markdown/lint/validation-counts.ts
new file mode 100644
index 000000000..98238656e
--- /dev/null
+++ b/packages/core/src/markdown/lint/validation-counts.ts
@@ -0,0 +1,36 @@
+export interface ValidationSourceCounts {
+ errorCount: number;
+ warningCount: number;
+}
+
+export interface ValidationCountsBySource {
+ lint: ValidationSourceCounts;
+ links: ValidationSourceCounts;
+}
+
+interface CountableDiagnostic {
+ severity: string;
+ source: string;
+}
+
+export type ValidationSourceKey = keyof ValidationCountsBySource;
+
+export const ZERO_SOURCE_COUNTS = {
+ errorCount: 0,
+ warningCount: 0,
+} as const satisfies ValidationSourceCounts;
+
+export function countDiagnosticsBySource(
+ diagnostics: readonly CountableDiagnostic[],
+): ValidationCountsBySource {
+ const counts: ValidationCountsBySource = {
+ lint: { errorCount: 0, warningCount: 0 },
+ links: { errorCount: 0, warningCount: 0 },
+ };
+ for (const diagnostic of diagnostics) {
+ const bucket = diagnostic.source === 'links' ? counts.links : counts.lint;
+ if (diagnostic.severity === 'error') bucket.errorCount += 1;
+ else bucket.warningCount += 1;
+ }
+ return counts;
+}
diff --git a/packages/core/src/schemas/api/_envelope.ts b/packages/core/src/schemas/api/_envelope.ts
index 06ff6a588..9962e9bf5 100644
--- a/packages/core/src/schemas/api/_envelope.ts
+++ b/packages/core/src/schemas/api/_envelope.ts
@@ -392,6 +392,13 @@ export const ProblemTypeSchema = z.enum([
// "change the resource (convert to JSON/JSONC/YAML) and retry" — not a
// never-retry malformed request.
'urn:ok:error:config-not-writable',
+ // `GET /api/audit` + `GET /api/lint/audit` abandon (409) a walk whose lint
+ // configuration changed underneath it. The walk resolves the native
+ // markdownlint cascade per document and yields between documents, so its
+ // result would otherwise mix both configurations — a plane true of neither.
+ // Retryable and self-correcting: the same mutation broadcasts `lint-config`,
+ // so the caller is already scheduling the walk that supersedes this one.
+ 'urn:ok:error:audit-superseded',
]) satisfies StandardSchemaV1;
export type ProblemType = z.infer<typeof ProblemTypeSchema>;
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index e121cac43..e9c03f67f 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -256,6 +256,7 @@ import {
UploadRequestSchema,
unwrapFrontmatterFences,
updateWorkspaceSearchCorpus,
+ ValidationAuditCountsResponseSchema,
ValidationAuditResponseSchema,
type ValidationDiagnostic,
type WorkspaceSearchCorpus,
@@ -374,7 +375,14 @@ import {
recordSkillInstall,
removeSkillInstall,
} from './installed-skills-marker.ts';
-import { auditProject, collectDocFiles, lintAndFixSource, lintDoc } from './lint/audit.ts';
+import {
+ AuditSupersededError,
+ auditProject,
+ collectDocFiles,
+ lintAndFixSource,
+ lintDoc,
+} from './lint/audit.ts';
+import { AuditCache } from './lint/audit-cache.ts';
import {
createEmptyFrontmatterSchemaFile,
deleteFrontmatterSchemaFile,
@@ -395,7 +403,13 @@ import {
resolveEffectiveLinterConfig,
resolveNativeConfigForDoc,
} from './lint/resolve-config.ts';
-import { createProjectValidators, runValidationAudit } from './lint/validation-audit.ts';
+import {
+ createProjectValidators,
+ type ProjectValidator,
+ runValidationAudit,
+ toValidationCountsPlane,
+ type ValidationAuditResult,
+} from './lint/validation-audit.ts';
import { validateMermaidFences } from './mermaid-validator.ts';
import {
extractPageIcon,
@@ -19580,6 +19594,40 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
// The editor reads the effective config; the Settings GUI writes native
// `.markdownlint.*` rules through the markdownlint-config endpoint.
+ /**
+ * Monotonic counter over server-side lint-config mutations, and the config
+ * half of {@link readAuditGeneration}: neither the native markdownlint rules
+ * nor the frontmatter-schema bodies appear in the base config, so a rule
+ * toggle moves no fingerprint and would otherwise be invisible to the audit.
+ *
+ * Bumped only through {@link signalLintConfigChanged}, which is also the sole
+ * `lint-config` CC1 emitter here — the two must move together or a mutation
+ * that converges other windows would leave audits on the superseded config.
+ */
+ let lintConfigEpoch = 0;
+ function signalLintConfigChanged(): void {
+ lintConfigEpoch += 1;
+ signalChannel?.('lint-config');
+ }
+
+ /**
+ * The world an audit plane would be true of: the lint configuration in force
+ * plus the branch whose content is on disk. The audit's coalescing key and
+ * its in-flight walks both rest on this one reader, so the two stay in step
+ * by construction.
+ *
+ * Branch belongs here for the same reason the config epoch does, one layer
+ * down: a switch replaces the content set wholesale, so a request issued
+ * after one must not attach to a walk started before it, and a walk spanning
+ * one must abandon itself rather than publish half of each branch.
+ *
+ * Compared for equality only, never ordered — a branch label carries no
+ * order. The space separator is unambiguous because a branch label is either
+ * a git branch name (refnames admit no spaces) or a `detached-<oid>` literal.
+ */
+ const readAuditGeneration = (): string =>
+ `${lintConfigEpoch} ${durabilityState.getActiveBranch()}`;
+
// Content-rule violations on a post-write document, for the agent write/edit
// advisory channel — the full validation plane, not just lint: every enabled
// lint source PLUS broken internal links, so an agent that writes a dead
@@ -19756,7 +19804,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
// toggle in one window leaves the rest linting against a stale config
// until they happen to refetch, which is what the frontmatter sibling
// below already avoids.
- signalChannel?.('lint-config');
+ signalLintConfigChanged();
try {
const base = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;
const configProblems: string[] = [];
@@ -19847,7 +19895,7 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
if (writeResult.action === 'created' || writeResult.action === 'deleted') {
signalChannel?.('files');
}
- signalChannel?.('lint-config');
+ signalLintConfigChanged();
try {
const base = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;
const configProblems: string[] = [];
@@ -20007,6 +20055,57 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
{ handler: 'lint', method: 'GET', skipBodyParse: true },
);
+ // One cache per server instance (not module-scoped): its keys carry contentDir,
+ // but a per-server lifetime also means a restart starts cold, which is the
+ // right blast radius for a disk-stamp-keyed cache.
+ const auditCache = new AuditCache();
+ /**
+ * Audits in flight, keyed by scope + config fingerprint. Every window runs the
+ * freshness triggers independently, and the Problems panel can refresh at the
+ * same moment, so a single config change can ask for the same whole-project
+ * walk several times over. Coalescing makes them one walk instead of N cold
+ * ones that each finish too late to warm the others' cache.
+ *
+ * The walk yields to the event loop, so a request issued after a config
+ * mutation or a branch switch IS parsed while an earlier walk is still
+ * running and could attach to it. The fingerprint alone would not stop that:
+ * it covers the BASE config, which never carries markdownlint `rules` (those
+ * come from the native `.markdownlint.*` cascade) nor frontmatter-schema
+ * bodies, and says nothing at all about which branch's content is on disk.
+ * {@link readAuditGeneration} is what makes the key move, which is why it is
+ * read here per request rather than captured once. The per-file cache keys on
+ * the fully-resolved config and the file's disk stamp, so nothing is cached
+ * under the wrong rules or the wrong branch's bytes either way.
+ */
+ const auditFlight = createSingleFlight<ValidationAuditResult>();
+
+ function runCoalescedAudit(
+ validators: readonly ProjectValidator[],
+ targetPath: string | undefined,
+ configFingerprint: string,
+ ): Promise<ValidationAuditResult> {
+ const key = `${configFingerprint} ${readAuditGeneration()} ${targetPath ?? ''}`;
+ return auditFlight.run(key, () => runValidationAudit(validators, { targetPath })).promise;
+ }
+
+ /**
+ * A superseded walk has no plane to report, so the caller gets a retryable
+ * 409 rather than a stale or mixed one. The store-side effect is exactly the
+ * effect of any failed audit — previous entries stand — and whichever change
+ * superseded this walk has already broadcast its own CC1 channel
+ * (`lint-config` for a config mutation, `branch-switched` for a switch), so
+ * the corrective walk is scheduled without the caller doing anything.
+ */
+ function respondAuditSuperseded(res: ServerResponse, handler: string): void {
+ errorResponse(
+ res,
+ 409,
+ 'urn:ok:error:audit-superseded',
+ 'The lint configuration or branch changed while the audit was running; re-run it.',
+ { handler },
+ );
+ }
+
const handleLintAudit = withValidation(
EmptyRequestSchema,
async (req, res) => {
@@ -20030,9 +20129,15 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
baseConfig,
targetPath: target,
liveSourceFor: liveLintSourceFor,
+ cache: auditCache,
+ auditGeneration: readAuditGeneration,
});
successResponse(res, 200, LintAuditResponseSchema, result, { handler: 'lint-audit' });
} catch (e) {
+ if (e instanceof AuditSupersededError) {
+ respondAuditSuperseded(res, 'lint-audit');
+ return;
+ }
errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to audit project.', {
handler: 'lint-audit',
cause: e,
@@ -20089,10 +20194,33 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {
linksValidation: getLinksValidationSetting?.(),
admittedDocNames: collectAdmittedDocNames,
docFilePathFor: (docName) => resolveDocFilePath(contentDir, docName),
+ cache: auditCache,
+ auditGeneration: readAuditGeneration,
});
- const result = await runValidationAudit(validators, { targetPath: target });
+ const result = await runCoalescedAudit(
+ validators,
+ target,
+ AuditCache.fingerprintConfig(baseConfig),
+ );
+ // `counts=1` tallies the same plane instead of enumerating it — the
+ // freshness path behind file-tree tints wants per-file counts, and on a
+ // large KB the enumerated bodies are tens of MB it discards on arrival.
+ if (url.searchParams.get('counts') === '1') {
+ successResponse(
+ res,
+ 200,
+ ValidationAuditCountsResponseSchema,
+ toValidationCountsPlane(result),
+ { handler: 'audit' },
+ );
+ return;
+ }
successResponse(res, 200, ValidationAuditResponseSchema, result, { handler: 'audit' });
} catch (e) {
+ if (e instanceof AuditSupersededError) {
+ respondAuditSuperseded(res, 'audit');
+ return;
+ }
errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to audit project.', {
handler: 'audit',
cause: e,
diff --git a/packages/server/src/lint/audit-cache.test.ts b/packages/server/src/lint/audit-cache.test.ts
new file mode 100644
index 000000000..a4f804fd4
--- /dev/null
+++ b/packages/server/src/lint/audit-cache.test.ts
@@ -0,0 +1,146 @@
+/**
+ * Behavioral tests for the audit result cache: key composition (every input a
+ * doc's diagnostics derive from), entry isolation from caller mutation, and
+ * LRU eviction under both the entry and byte bounds.
+ */
+
+import type { LintDiagnostic, LinterConfig } from '@inkeep/open-knowledge-core';
+import { DEFAULT_LINTER_CONFIG } from '@inkeep/open-knowledge-core';
+import { describe, expect, test } from 'vitest';
+import { AuditCache } from './audit-cache.ts';
+
+function diagnostic(code: string): LintDiagnostic {
+ return {
+ range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } },
+ severity: 'warning',
+ source: 'markdownlint',
+ code,
+ message: `${code} fired`,
+ };
+}
+
+const BASE_KEY = {
+ contentDir: '/kb',
+ docRelPath: 'notes/a.md',
+ mtimeMs: 1_700_000_000_000,
+ size: 512,
+ configFingerprint: 'fp-1',
+};
+
+function withMarkdownlint(rules: Record<string, unknown>): LinterConfig {
+ const config = structuredClone(DEFAULT_LINTER_CONFIG);
+ config.plugins.markdownlint.enabled = true;
+ config.plugins.markdownlint.rules = rules as LinterConfig['plugins']['markdownlint']['rules'];
+ return config;
+}
+
+describe('AuditCache.fingerprintConfig', () => {
+ test('is stable for equal configs and differs when a rule changes', () => {
+ const a = AuditCache.fingerprintConfig(withMarkdownlint({ MD013: true }));
+ const b = AuditCache.fingerprintConfig(withMarkdownlint({ MD013: true }));
+ const toggledOff = AuditCache.fingerprintConfig(withMarkdownlint({ MD013: false }));
+ expect(a).toBe(b);
+ expect(toggledOff).not.toBe(a);
+ });
+
+ test('differs when a rule OPTION changes, not just its enablement', () => {
+ const at80 = AuditCache.fingerprintConfig(withMarkdownlint({ MD013: { line_length: 80 } }));
+ const at120 = AuditCache.fingerprintConfig(withMarkdownlint({ MD013: { line_length: 120 } }));
+ expect(at120).not.toBe(at80);
+ });
+
+ test('differs when a plugin is enabled', () => {
+ const off = AuditCache.fingerprintConfig(DEFAULT_LINTER_CONFIG);
+ const on = AuditCache.fingerprintConfig(withMarkdownlint({}));
+ expect(on).not.toBe(off);
+ });
+});
+
+describe('AuditCache.key', () => {
+ test('every component participates — changing any one yields a fresh key', () => {
+ const base = AuditCache.key(BASE_KEY);
+ const variants = [
+ { ...BASE_KEY, contentDir: '/other-kb' },
+ { ...BASE_KEY, docRelPath: 'notes/b.md' },
+ { ...BASE_KEY, mtimeMs: BASE_KEY.mtimeMs + 1 },
+ { ...BASE_KEY, size: BASE_KEY.size + 1 },
+ { ...BASE_KEY, configFingerprint: 'fp-2' },
+ ];
+ for (const variant of variants) {
+ expect(AuditCache.key(variant)).not.toBe(base);
+ }
+ expect(AuditCache.key({ ...BASE_KEY })).toBe(base);
+ });
+});
+
+describe('AuditCache', () => {
+ test('a miss reports null and a stored entry reads back', () => {
+ const cache = new AuditCache();
+ const key = AuditCache.key(BASE_KEY);
+ expect(cache.get(key)).toBeNull();
+ expect(cache.stats()).toMatchObject({ hits: 0, misses: 1, entries: 0 });
+
+ cache.set(key, [diagnostic('MD010')]);
+ expect(cache.get(key)).toEqual([diagnostic('MD010')]);
+ expect(cache.stats()).toMatchObject({ hits: 1, misses: 1, entries: 1 });
+ });
+
+ test('a caller mutating what it received cannot corrupt the entry', () => {
+ const cache = new AuditCache();
+ const key = AuditCache.key(BASE_KEY);
+ cache.set(key, [diagnostic('MD010'), diagnostic('MD012')]);
+
+ const first = cache.get(key);
+ expect(first).not.toBeNull();
+ // The audit merges and sorts the array it gets back, in place.
+ first?.splice(0, 1);
+ first?.push(diagnostic('INJECTED'));
+
+ expect(cache.get(key)).toEqual([diagnostic('MD010'), diagnostic('MD012')]);
+ });
+
+ test('re-setting a key replaces rather than double-counting its bytes', () => {
+ const cache = new AuditCache();
+ const key = AuditCache.key(BASE_KEY);
+ cache.set(key, [diagnostic('MD010')]);
+ const afterFirst = cache.stats().bytes;
+ cache.set(key, [diagnostic('MD010')]);
+ expect(cache.stats()).toMatchObject({ entries: 1, bytes: afterFirst });
+ });
+
+ test('evicts least-recently-used first once the entry bound is exceeded', () => {
+ const cache = new AuditCache({ maxEntries: 2 });
+ const keyFor = (doc: string) => AuditCache.key({ ...BASE_KEY, docRelPath: doc });
+ cache.set(keyFor('a.md'), [diagnostic('A')]);
+ cache.set(keyFor('b.md'), [diagnostic('B')]);
+ // Touch `a` so `b` becomes the least recently used.
+ expect(cache.get(keyFor('a.md'))).not.toBeNull();
+ cache.set(keyFor('c.md'), [diagnostic('C')]);
+
+ expect(cache.stats().entries).toBe(2);
+ expect(cache.get(keyFor('b.md'))).toBeNull();
+ expect(cache.get(keyFor('a.md'))).not.toBeNull();
+ expect(cache.get(keyFor('c.md'))).not.toBeNull();
+ });
+
+ test('evicts under the byte bound even when the entry count is small', () => {
+ // One diagnostic already exceeds this, so every insert forces eviction.
+ const cache = new AuditCache({ maxBytes: 40 });
+ const keyFor = (doc: string) => AuditCache.key({ ...BASE_KEY, docRelPath: doc });
+ cache.set(keyFor('a.md'), [diagnostic('A')]);
+ cache.set(keyFor('b.md'), [diagnostic('B')]);
+
+ // The bound is honored down to a floor of one entry — the most recent
+ // insert is always retained, so a single oversized doc still caches.
+ expect(cache.stats().entries).toBe(1);
+ expect(cache.get(keyFor('b.md'))).not.toBeNull();
+ expect(cache.get(keyFor('a.md'))).toBeNull();
+ });
+
+ test('clear drops entries and counters', () => {
+ const cache = new AuditCache();
+ cache.set(AuditCache.key(BASE_KEY), [diagnostic('MD010')]);
+ cache.clear();
+ expect(cache.stats()).toEqual({ hits: 0, misses: 0, entries: 0, bytes: 0 });
+ });
+});
diff --git a/packages/server/src/lint/audit-cache.ts b/packages/server/src/lint/audit-cache.ts
new file mode 100644
index 000000000..93948fbc5
--- /dev/null
+++ b/packages/server/src/lint/audit-cache.ts
@@ -0,0 +1,193 @@
+/**
+ * Per-file lint-result cache for the project audit walk. The walk is serial and
+ * CPU-bound in the lint engines (milliseconds per doc), so on a large KB a
+ * whole-project audit costs tens of seconds — and the freshness triggers behind
+ * file-tree tints re-run it far more often than the manual audit button ever
+ * did.
+ *
+ * A cached entry is keyed on everything a doc's diagnostics derive from: its
+ * identity, its disk stamp, and a fingerprint of the fully-resolved config it
+ * was linted with (base + native `.markdownlint.*` cascade + frontmatter
+ * schemas). So an audit at unchanged config over unchanged files does no lint
+ * work at all — which is what the refresh button, the post-`Fix all` re-audit,
+ * and per-doc revalidation all are.
+ *
+ * What it deliberately does NOT accelerate: a rule toggle. Changing the
+ * effective config changes the fingerprint for every doc, so a genuine toggle
+ * is a full re-walk by construction. Making THAT cheap needs either a
+ * worker-thread fan-out or an all-rules superset filtered per active rule set;
+ * both are larger changes than this cache.
+ *
+ * Docs read from a live CRDT overlay are never cached — their bytes move
+ * without touching the disk stamp the key rests on.
+ */
+
+import { createHash } from 'node:crypto';
+import type { LintDiagnostic, LinterConfig } from '@inkeep/open-knowledge-core';
+
+/**
+ * Entry ceiling. A config change mints new keys for the docs it governs without
+ * dropping the ones they replace, so the live set is one generation per project
+ * plus however many superseded generations have not yet aged out through LRU —
+ * this is a leak bound, not a working-set target. Nothing purges a generation
+ * eagerly on purpose: native `.markdownlint.*` files cascade, so a config write
+ * invalidates only the subtree it governs and a blanket clear would discard
+ * still-valid entries for every unaffected doc.
+ */
+const MAX_ENTRIES = 10_000;
+
+/**
+ * Byte ceiling over the serialized payloads. Entry count alone is a poor memory
+ * bound: a KB where every doc carries dozens of findings holds far more per
+ * entry than one that is nearly clean.
+ */
+const MAX_BYTES = 64 * 1024 * 1024;
+
+/**
+ * Entries hold each doc's diagnostics SERIALIZED, not as live objects. A
+ * 6k-doc KB produces ~150k diagnostics, and retaining those as ~750k nested
+ * objects across a walk costs more in GC scanning than the lint work it saves
+ * — measured at 2.6x the uncached audit. One flat string per doc is a single
+ * allocation the collector never has to trace into, which turns the retention
+ * cost back into noise; the price is a parse on hit, far below a re-lint.
+ */
+interface CacheEntry {
+ json: string;
+ /**
+ * UTF-8 byte length of `json`, computed once at insert. Accounting on this
+ * rather than `json.length` (UTF-16 code units) keeps `MAX_BYTES` a true byte
+ * ceiling over the serialized payloads for non-Latin diagnostic text.
+ */
+ bytes: number;
+}
+
+export interface AuditCacheStats {
+ hits: number;
+ misses: number;
+ entries: number;
+ bytes: number;
+}
+
+export interface AuditCacheLimits {
+ maxEntries?: number;
+ maxBytes?: number;
+}
+
+/**
+ * Insertion-ordered so eviction is least-recently-used: a hit re-inserts its
+ * key at the back (`Map` iteration order is insertion order, and `delete` +
+ * `set` is the idiomatic JS promotion).
+ */
+export class AuditCache {
+ private readonly entries = new Map<string, CacheEntry>();
+ private readonly maxEntries: number;
+ private readonly maxBytes: number;
+ private byteCount = 0;
+ private hits = 0;
+ private misses = 0;
+
+ constructor(limits: AuditCacheLimits = {}) {
+ this.maxEntries = limits.maxEntries ?? MAX_ENTRIES;
+ this.maxBytes = limits.maxBytes ?? MAX_BYTES;
+ }
+
+ /**
+ * Fingerprint a resolved config. Hashes the config itself rather than the
+ * inputs that produced it, so no assumption is needed about which inputs
+ * reach diagnostics — base rules, a governing native file's rules, and
+ * loaded frontmatter schema bodies are all serializable and all included.
+ */
+ static fingerprintConfig(config: LinterConfig): string {
+ return createHash('sha1').update(JSON.stringify(config)).digest('base64');
+ }
+
+ /**
+ * `mtimeMs` + `size` is the standard content stamp. It can theoretically miss
+ * a same-millisecond, same-length rewrite; every write path that matters here
+ * either goes through the live-CRDT overlay (never cached) or lands a
+ * different length or timestamp.
+ */
+ static key(parts: {
+ contentDir: string;
+ docRelPath: string;
+ mtimeMs: number;
+ size: number;
+ configFingerprint: string;
+ }): string {
+ // contentDir is part of the key so one process serving several projects —
+ // or a test run booting many servers over identically-named fixture docs —
+ // cannot collide.
+ return [
+ parts.contentDir,
+ parts.docRelPath,
+ parts.mtimeMs,
+ parts.size,
+ parts.configFingerprint,
+ // NUL separator, written as an escape so this source stays plain text: a raw
+ // NUL byte makes git classify the file as binary and hide its diffs. Paths and
+ // base64 fingerprints can contain spaces and slashes but never NUL, so this is
+ // the one separator that cannot let two different tuples build the same key.
+ ].join('\u0000');
+ }
+
+ /**
+ * Cached diagnostics for `key`, or null. Deserialized fresh each time, so a
+ * caller that sorts or splices what it receives cannot corrupt the entry.
+ * The payload is this cache's own `JSON.stringify` output, so the parse is
+ * total — no failure branch to handle.
+ */
+ get(key: string): LintDiagnostic[] | null {
+ const entry = this.entries.get(key);
+ if (entry === undefined) {
+ this.misses += 1;
+ return null;
+ }
+ this.hits += 1;
+ this.entries.delete(key);
+ this.entries.set(key, entry);
+ return JSON.parse(entry.json) as LintDiagnostic[];
+ }
+
+ set(key: string, diagnostics: readonly LintDiagnostic[]): void {
+ const existing = this.entries.get(key);
+ if (existing !== undefined) {
+ this.byteCount -= existing.bytes;
+ this.entries.delete(key);
+ }
+ const json = JSON.stringify(diagnostics);
+ const bytes = Buffer.byteLength(json, 'utf8');
+ this.entries.set(key, { json, bytes });
+ this.byteCount += bytes;
+ this.evictToBounds();
+ }
+
+ private evictToBounds(): void {
+ while (
+ (this.entries.size > this.maxEntries || this.byteCount > this.maxBytes) &&
+ this.entries.size > 1
+ ) {
+ // `keys().next()` is the least-recently-used key (insertion order).
+ const oldest = this.entries.keys().next();
+ if (oldest.done === true) return;
+ const evicted = this.entries.get(oldest.value);
+ this.entries.delete(oldest.value);
+ if (evicted !== undefined) this.byteCount -= evicted.bytes;
+ }
+ }
+
+ stats(): AuditCacheStats {
+ return {
+ hits: this.hits,
+ misses: this.misses,
+ entries: this.entries.size,
+ bytes: this.byteCount,
+ };
+ }
+
+ clear(): void {
+ this.entries.clear();
+ this.byteCount = 0;
+ this.hits = 0;
+ this.misses = 0;
+ }
+}
diff --git a/packages/server/src/lint/audit-yield.test.ts b/packages/server/src/lint/audit-yield.test.ts
new file mode 100644
index 000000000..3fdef6b4d
--- /dev/null
+++ b/packages/server/src/lint/audit-yield.test.ts
@@ -0,0 +1,116 @@
+/**
+ * The audit walk must not hold the event loop, and a walk whose world (lint
+ * configuration, or the branch whose content is on disk) changed underneath it
+ * must not return a half-old-half-new plane.
+ *
+ * Both properties are observed through real event-loop behavior rather than
+ * instrumentation: a `setInterval` that only ticks if the loop is serviced,
+ * and a `setTimeout` that only fires if the walk yields before it finishes.
+ */
+
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DEFAULT_LINTER_CONFIG, type LinterConfig } from '@inkeep/open-knowledge-core';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import { AuditSupersededError, auditProject } from './audit.ts';
+
+let root: string;
+
+const base: LinterConfig = {
+ ...DEFAULT_LINTER_CONFIG,
+ plugins: {
+ ...DEFAULT_LINTER_CONFIG.plugins,
+ markdownlint: { ...DEFAULT_LINTER_CONFIG.plugins.markdownlint, enabled: true },
+ },
+};
+
+/**
+ * Big enough that an unyielding walk visibly stalls the loop (measured at
+ * ~300ms, ~30 missed ticks of a 10ms interval), small enough to stay a unit
+ * test. Every line carries a hard tab so markdownlint has real work per doc.
+ */
+const DOC_COUNT = 100;
+const LINE_COUNT = 150;
+
+/** Fires early enough to land mid-walk, late enough that the walk has started. */
+const MID_WALK_MS = 20;
+
+function seedCorpus(): void {
+ const lines = ['# Title', ''];
+ for (let i = 0; i < LINE_COUNT; i += 1) {
+ lines.push(`Paragraph ${i} with\ta hard tab and some filler text.`, '');
+ }
+ const text = lines.join('\n');
+ for (let i = 0; i < DOC_COUNT; i += 1) {
+ const dir = join(root, `folder-${i % 10}`);
+ mkdirSync(dir, { recursive: true });
+ writeFileSync(join(dir, `doc-${i}.md`), text, 'utf-8');
+ }
+}
+
+beforeEach(() => {
+ root = realpathSync(mkdtempSync(join(tmpdir(), 'ok-audit-yield-')));
+ seedCorpus();
+});
+afterEach(() => {
+ rmSync(root, { recursive: true, force: true });
+});
+
+describe('auditProject event-loop liveness', () => {
+ test('a timer keeps ticking while the walk runs', async () => {
+ let ticks = 0;
+ const interval = setInterval(() => {
+ ticks += 1;
+ }, 10);
+ try {
+ const result = await auditProject({ projectDir: root, contentDir: root, baseConfig: base });
+ expect(result.fileCount).toBe(DOC_COUNT);
+ } finally {
+ clearInterval(interval);
+ }
+ // A synchronous walk services zero ticks over its whole duration. The
+ // floor is far below the ~30 a 10ms interval would get across this
+ // corpus, so a loaded machine cannot push it under.
+ expect(ticks).toBeGreaterThanOrEqual(5);
+ });
+});
+
+describe('auditProject generation supersession', () => {
+ // The walk compares the injected token for equality and nothing else, so
+ // which half of it moved — lint config or branch — is invisible here. The
+ // branch half is pinned end-to-end through the HTTP surface instead, in
+ // `audit-branch-generation.test.ts`.
+ test('abandons the walk when the generation moves mid-walk', async () => {
+ let generation = '0 main';
+ // A real timer, not a counting stub: it can only fire before the walk
+ // finishes if the walk actually yields to the loop.
+ const bump = setTimeout(() => {
+ generation = '1 main';
+ }, MID_WALK_MS);
+ try {
+ await expect(
+ auditProject({
+ projectDir: root,
+ contentDir: root,
+ baseConfig: base,
+ auditGeneration: () => generation,
+ }),
+ ).rejects.toBeInstanceOf(AuditSupersededError);
+ } finally {
+ clearTimeout(bump);
+ }
+ expect(generation).toBe('1 main');
+ });
+
+ test('completes normally when the generation holds', async () => {
+ const result = await auditProject({
+ projectDir: root,
+ contentDir: root,
+ baseConfig: base,
+ auditGeneration: () => '7 main',
+ });
+ expect(result.fileCount).toBe(DOC_COUNT);
+ expect(result.warningCount).toBeGreaterThan(0);
+ });
+});
diff --git a/packages/server/src/lint/audit.test.ts b/packages/server/src/lint/audit.test.ts
index bd84d54f9..e17651e5c 100644
--- a/packages/server/src/lint/audit.test.ts
+++ b/packages/server/src/lint/audit.test.ts
@@ -10,6 +10,7 @@ import { join } from 'node:path';
import { DEFAULT_LINTER_CONFIG, type LinterConfig } from '@inkeep/open-knowledge-core';
import { afterEach, beforeEach, describe, expect, test } from 'vitest';
import { auditProject, lintDoc } from './audit.ts';
+import { AuditCache } from './audit-cache.ts';
let root: string;
@@ -198,4 +199,119 @@ describe('auditProject', () => {
expect(audit.files).toEqual([]);
expect(audit.warningCount).toBe(0);
});
+
+ describe('with a result cache', () => {
+ test('a second audit at unchanged config re-lints nothing and agrees', async () => {
+ write('a.md', DOC_WITH_TAB);
+ write('b.md', DOC_WITH_TAB);
+ write('clean.md', CLEAN_DOC);
+ const cache = new AuditCache();
+ const opts = { projectDir: root, contentDir: root, baseConfig: base, cache };
+
+ const first = await auditProject(opts);
+ expect(cache.stats()).toMatchObject({ hits: 0, misses: 3, entries: 3 });
+
+ const second = await auditProject(opts);
+ expect(cache.stats().hits).toBe(3);
+ // The cached plane must be indistinguishable from the freshly-linted one.
+ expect(second.files).toEqual(first.files);
+ expect(second.warningCount).toBe(first.warningCount);
+ expect(second.errorCount).toBe(first.errorCount);
+ });
+
+ test('editing a doc invalidates only that doc', async () => {
+ write('a.md', DOC_WITH_TAB);
+ write('b.md', DOC_WITH_TAB);
+ const cache = new AuditCache();
+ const opts = { projectDir: root, contentDir: root, baseConfig: base, cache };
+ await auditProject(opts);
+
+ // A different length guarantees a distinct stamp regardless of timer
+ // granularity, which is the property the key actually rests on.
+ write('a.md', `${DOC_WITH_TAB}\nAnother\tline with a tab.\n`);
+ const after = await auditProject(opts);
+
+ expect(cache.stats().hits).toBe(1);
+ expect(after.files.map((f) => f.file).sort()).toEqual(['a.md', 'b.md']);
+ });
+
+ test('a rule change invalidates every doc', async () => {
+ write('a.md', DOC_WITH_TAB);
+ write('b.md', DOC_WITH_TAB);
+ const cache = new AuditCache();
+ await auditProject({ projectDir: root, contentDir: root, baseConfig: base, cache });
+ expect(cache.stats().misses).toBe(2);
+
+ const md010Off: LinterConfig = {
+ ...base,
+ plugins: {
+ ...base.plugins,
+ markdownlint: { ...base.plugins.markdownlint, rules: { MD010: false } },
+ },
+ };
+ const after = await auditProject({
+ projectDir: root,
+ contentDir: root,
+ baseConfig: md010Off,
+ cache,
+ });
+
+ // Nothing carries over: the config every entry was linted under is gone.
+ expect(cache.stats().hits).toBe(0);
+ expect(after.files.some((f) => f.diagnostics.some((d) => d.code === 'MD010'))).toBe(false);
+ });
+
+ test('editing the native .markdownlint.json invalidates the cache', async () => {
+ // The base config is unchanged here — only the on-disk cascade moved. The
+ // key rests on the RESOLVED config, so this has to invalidate too, or a
+ // native-file edit would serve diagnostics for the superseded rules.
+ write('a.md', DOC_WITH_TAB);
+ write('.markdownlint.json', JSON.stringify({ MD010: true }));
+ const cache = new AuditCache();
+ const opts = { projectDir: root, contentDir: root, baseConfig: base, cache };
+
+ const before = await auditProject(opts);
+ expect(before.files.some((f) => f.diagnostics.some((d) => d.code === 'MD010'))).toBe(true);
+
+ write('.markdownlint.json', JSON.stringify({ MD010: false }));
+ const after = await auditProject(opts);
+
+ expect(cache.stats().hits).toBe(0);
+ expect(after.files.some((f) => f.diagnostics.some((d) => d.code === 'MD010'))).toBe(false);
+ });
+
+ test('a doc served from the live CRDT overlay is never cached', async () => {
+ write('loaded.md', CLEAN_DOC);
+ const cache = new AuditCache();
+ const opts = {
+ projectDir: root,
+ contentDir: root,
+ baseConfig: base,
+ cache,
+ // Live bytes move without touching the disk stamp the key rests on, so
+ // caching them would serve a stale plane for the doc being edited.
+ liveSourceFor: (rel: string) => (rel === 'loaded.md' ? DOC_WITH_TAB : null),
+ };
+ const first = await auditProject(opts);
+ const second = await auditProject(opts);
+
+ expect(cache.stats()).toMatchObject({ hits: 0, misses: 0, entries: 0 });
+ expect(first.files.map((f) => f.file)).toEqual(['loaded.md']);
+ expect(second.files).toEqual(first.files);
+ });
+
+ test('config-resolution problems still surface on a cache hit', async () => {
+ write('a.md', DOC_WITH_TAB);
+ write('.markdownlint.json', '{ not valid json');
+ const cache = new AuditCache();
+ const opts = { projectDir: root, contentDir: root, baseConfig: base, cache };
+
+ const first = await auditProject(opts);
+ expect(first.warnings.length).toBeGreaterThan(0);
+ // The warning channel must not thin out as the cache warms — a malformed
+ // config file has to keep reporting itself on every audit.
+ const second = await auditProject(opts);
+ expect(second.warnings).toEqual(first.warnings);
+ });
+ });
});
diff --git a/packages/server/src/lint/audit.ts b/packages/server/src/lint/audit.ts
index b00840af0..3d8345b8b 100644
--- a/packages/server/src/lint/audit.ts
+++ b/packages/server/src/lint/audit.ts
@@ -8,6 +8,7 @@
import { readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
import { isAbsolute, join, relative, resolve } from 'node:path';
+import { setImmediate as yieldToEventLoop } from 'node:timers/promises';
import {
fixDocument,
type LintDiagnostic,
@@ -18,6 +19,7 @@ import {
import { SymlinkEscapeError } from '../apply-managed-rename.ts';
import { createContentFilter } from '../content-filter.ts';
import { isWithinContentDir } from '../content-path.ts';
+import { AuditCache } from './audit-cache.ts';
import { unmatchedAppliesToProblems } from './frontmatter-schemas.ts';
import { composeFrontmatterSchemasConfig, resolveEffectiveLinterConfig } from './resolve-config.ts';
@@ -35,6 +37,36 @@ export interface AuditResult {
warnings: string[];
}
+/**
+ * Raised when the world the walk was linting changed underneath it — the lint
+ * configuration, or the branch whose content it was reading. Either way the
+ * walk's own result would mix docs from both sides of the change, so the
+ * caller must discard it rather than publish a plane that is true of no
+ * single configuration and no single branch.
+ */
+export class AuditSupersededError extends Error {
+ constructor(message = 'the lint configuration or branch changed during the audit walk') {
+ super(message);
+ this.name = 'AuditSupersededError';
+ }
+}
+
+/**
+ * How long the walk may hold the loop between yields. Time-sliced rather than
+ * every-N-documents because per-doc cost spans orders of magnitude (a stub vs
+ * a thousand-line doc under every rule), so a fixed count gives slices whose
+ * length is unbounded in the worst case.
+ *
+ * At this size a whole-project walk gives up the loop tens of times per second
+ * — enough that HTTP requests, CC1 signals, fs-watcher events and persistence
+ * timers keep being serviced — for a few percent of added wall time.
+ *
+ * It is a floor, not a ceiling: the yield sits between documents, so a single
+ * document costlier than the slice still holds the loop for its own duration.
+ * Going finer would need the lint engines themselves to become interruptible.
+ */
+const YIELD_SLICE_MS = 8;
+
export interface AuditOptions {
projectDir: string;
contentDir: string;
@@ -48,6 +80,30 @@ export interface AuditOptions {
* problems the live doc no longer has, and every "fix" is a clean no-op.
*/
liveSourceFor?: (docRelPath: string) => string | null;
+ /**
+ * Reuse per-file results across audits at unchanged config. Omitted → every
+ * doc is re-linted. Docs served from `liveSourceFor` bypass it regardless:
+ * their bytes move without touching the disk stamp the key rests on.
+ */
+ cache?: AuditCache;
+ /**
+ * Reads a token naming the world this walk's plane would be true of: the
+ * lint configuration in force AND the branch whose content is on disk.
+ * Injected rather than imported so this module stays free of server HTTP
+ * state. Compared for equality only — a branch label has no order — so it is
+ * a token, not a counter.
+ *
+ * Both inputs move underneath a walk. The walk resolves the native
+ * `.markdownlint.*` cascade per document, so a config write landing between
+ * two of its yields would leave earlier docs linted under the old rules and
+ * later ones under the new; a branch switch replaces the content set
+ * wholesale on disk, so one landing mid-walk leaves earlier docs read from
+ * the old branch and later ones from the new. Either way the result is a
+ * plane true of no single world. Sampled at each yield; a move abandons the
+ * walk with {@link AuditSupersededError}. Omitted → no supersession check,
+ * which is correct for callers that cannot observe either change.
+ */
+ auditGeneration?: () => string;
}
/** Lint a single document (live CRDT source when loaded, else disk) with its
@@ -55,24 +111,50 @@ export interface AuditOptions {
export async function lintDoc(
opts: AuditOptions & { docRelPath: string; onConfigProblem?: (problem: string) => void },
): Promise<FileLintResult> {
- const { projectDir, contentDir, baseConfig, docRelPath, onConfigProblem, liveSourceFor } = opts;
+ const { projectDir, contentDir, baseConfig, docRelPath, onConfigProblem, liveSourceFor, cache } =
+ opts;
const live = liveSourceFor?.(docRelPath) ?? null;
- let text: string;
- if (live !== null) {
- text = live;
- } else {
- // Symlinks inside the content dir are supported (realpath-based identity),
- // but an escape must be refused before the read: lint diagnostics echo
- // source text, so linting an escaped symlink is an arbitrary-file read.
- const canonical = resolveCanonicalDocPath(join(contentDir, docRelPath), contentDir);
- text = readFileSync(canonical, 'utf-8');
- }
+ // Resolved before the cache probe because the resolved config IS part of the
+ // key — and unconditionally, so a config-resolution problem still reaches
+ // `onConfigProblem` on a cache hit (the audit aggregates those into its
+ // top-level warnings, which must not thin out as the cache warms).
const cfg = resolveEffectiveLinterConfig(contentDir, baseConfig, {
docName: docRelPath,
projectDir,
onProblem: onConfigProblem,
});
- return { file: docRelPath, diagnostics: await lintDocument(text, cfg, docRelPath) };
+ if (live !== null) {
+ return { file: docRelPath, diagnostics: await lintDocument(live, cfg, docRelPath) };
+ }
+ // Symlinks inside the content dir are supported (realpath-based identity),
+ // but an escape must be refused before the read: lint diagnostics echo
+ // source text, so linting an escaped symlink is an arbitrary-file read.
+ const canonical = resolveCanonicalDocPath(join(contentDir, docRelPath), contentDir);
+ let cacheKey: string | null = null;
+ if (cache !== undefined) {
+ // A missing/unreadable stamp just skips the cache — the read below reports
+ // the real failure, and guessing a key would be worse than re-linting.
+ try {
+ const stat = statSync(canonical);
+ cacheKey = AuditCache.key({
+ contentDir,
+ docRelPath,
+ mtimeMs: stat.mtimeMs,
+ size: stat.size,
+ configFingerprint: AuditCache.fingerprintConfig(cfg),
+ });
+ } catch {
+ cacheKey = null;
+ }
+ if (cacheKey !== null) {
+ const cached = cache.get(cacheKey);
+ if (cached !== null) return { file: docRelPath, diagnostics: cached };
+ }
+ }
+ const text = readFileSync(canonical, 'utf-8');
+ const diagnostics = await lintDocument(text, cfg, docRelPath);
+ if (cacheKey !== null) cache?.set(cacheKey, diagnostics);
+ return { file: docRelPath, diagnostics };
}
/**
@@ -155,8 +237,11 @@ export function collectDocFiles(opts: {
export async function auditProject(
opts: AuditOptions & { targetPath?: string },
): Promise<AuditResult> {
- const { projectDir, contentDir, baseConfig, targetPath } = opts;
+ const { projectDir, contentDir, baseConfig, targetPath, auditGeneration } = opts;
const warnings: string[] = [];
+ // Sampled before the first yield, so it is the generation every doc in this
+ // walk is linted under until proven otherwise.
+ const startGeneration = auditGeneration?.();
const docFiles: string[] = [];
const scope = resolveScope(targetPath, contentDir);
@@ -223,7 +308,18 @@ export async function auditProject(
onConfigProblem(problem);
}
}
+ let sliceStartedAt = performance.now();
for (const rel of docFiles) {
+ if (performance.now() - sliceStartedAt >= YIELD_SLICE_MS) {
+ // A macrotask, not a microtask: `await Promise.resolve()` (or an async
+ // callee that never awaits real I/O, which is what the lint engines are)
+ // drains on the same turn and never lets the loop reach its poll phase.
+ await yieldToEventLoop();
+ if (auditGeneration !== undefined && auditGeneration() !== startGeneration) {
+ throw new AuditSupersededError();
+ }
+ sliceStartedAt = performance.now();
+ }
let result: FileLintResult;
try {
result = await lintDoc({
@@ -233,6 +329,7 @@ export async function auditProject(
docRelPath: rel,
onConfigProblem,
liveSourceFor: opts.liveSourceFor,
+ cache: opts.cache,
});
} catch (e) {
warnings.push(`could not lint ${rel}: ${errMsg(e)}`);
diff --git a/packages/server/src/lint/validation-audit.test.ts b/packages/server/src/lint/validation-audit.test.ts
index e0176c164..45babd7fb 100644
--- a/packages/server/src/lint/validation-audit.test.ts
+++ b/packages/server/src/lint/validation-audit.test.ts
@@ -12,6 +12,7 @@ import {
DEFAULT_LINTER_CONFIG,
type LinterConfig,
SUPPORTED_DOC_EXTENSIONS,
+ ValidationAuditCountsResponseSchema,
ValidationAuditResponseSchema,
} from '@inkeep/open-knowledge-core';
import { afterEach, beforeEach, describe, expect, test } from 'vitest';
@@ -19,6 +20,7 @@ import { BacklinkIndex } from '../backlink-index.ts';
import {
createProjectValidators,
runValidationAudit,
+ toValidationCountsPlane,
type ValidationAuditDeps,
} from './validation-audit.ts';
@@ -346,3 +348,60 @@ describe('runValidationAudit', () => {
expect(ValidationAuditResponseSchema.parse(result)).toEqual(result);
});
});
+
+describe('toValidationCountsPlane', () => {
+ test('tallies the merged plane per file and per source, dropping the bodies', async () => {
+ // One doc carrying BOTH a lint finding and a dead link, so the split is
+ // observable rather than inferred.
+ seedDoc('a', '# A\n\n\tTab line.\n\nSee [[ghost]].\n');
+ seedDoc('b', '# B\n\n\tTab line.\n');
+ const result = await runValidationAudit(createProjectValidators(deps()));
+ const counts = toValidationCountsPlane(result);
+
+ expect(ValidationAuditCountsResponseSchema.safeParse(counts).success).toBe(true);
+ const a = counts.files.find((f) => f.file === 'a.md');
+ expect(a?.links).toEqual({ errorCount: 0, warningCount: 1 });
+ expect(a?.lint.warningCount).toBeGreaterThan(0);
+ expect(a?.lint.errorCount).toBe(0);
+
+ // Rollups and the file set carry over from the enumerated plane verbatim.
+ expect(counts.files.map((f) => f.file)).toEqual(result.files.map((f) => f.file));
+ expect(counts.fileCount).toBe(result.fileCount);
+ expect(counts.errorCount).toBe(result.errorCount);
+ expect(counts.warningCount).toBe(result.warningCount);
+ expect(counts.warnings).toEqual(result.warnings);
+ });
+
+ test('per-file tallies sum to the plane rollups', async () => {
+ seedDoc('a', '# A\n\n\tTab.\n\nSee [[ghost]] and [[phantom]].\n');
+ seedDoc('b', '# B\n\n\tTab.\n');
+ const result = await runValidationAudit(createProjectValidators(deps()));
+ const counts = toValidationCountsPlane(result);
+
+ const errors = counts.files.reduce((n, f) => n + f.lint.errorCount + f.links.errorCount, 0);
+ const warnings = counts.files.reduce(
+ (n, f) => n + f.lint.warningCount + f.links.warningCount,
+ 0,
+ );
+ expect(errors).toBe(result.errorCount);
+ expect(warnings).toBe(result.warningCount);
+ });
+
+ test('an empty plane tallies to an empty plane', () => {
+ expect(
+ toValidationCountsPlane({
+ files: [],
+ fileCount: 7,
+ errorCount: 0,
+ warningCount: 0,
+ warnings: ['a config warning'],
+ }),
+ ).toEqual({
+ files: [],
+ fileCount: 7,
+ errorCount: 0,
+ warningCount: 0,
+ warnings: ['a config warning'],
+ });
+ });
+});
diff --git a/packages/server/src/lint/validation-audit.ts b/packages/server/src/lint/validation-audit.ts
index c78aae652..2e9334c6f 100644
--- a/packages/server/src/lint/validation-audit.ts
+++ b/packages/server/src/lint/validation-audit.ts
@@ -9,15 +9,18 @@
*/
import {
+ countDiagnosticsBySource,
DEFAULT_LINKS_VALIDATION,
type LinksValidationSetting,
type LinterConfig,
SUPPORTED_DOC_EXTENSIONS,
type ValidationDiagnostic,
+ type ValidationDocCounts,
} from '@inkeep/open-knowledge-core';
import type { DerivedDocumentIndexApiPort } from '../derived-document-index.ts';
import { getLogger } from '../logger.ts';
-import { auditProject } from './audit.ts';
+import { AuditSupersededError, auditProject } from './audit.ts';
+import type { AuditCache } from './audit-cache.ts';
type DeadLinksResult = Awaited<ReturnType<DerivedDocumentIndexApiPort['getDeadLinks']>>;
@@ -42,6 +45,36 @@ export interface ValidationAuditResult {
warnings: string[];
}
+export interface ValidationAuditCountsResult {
+ files: ValidationDocCounts[];
+ fileCount: number;
+ errorCount: number;
+ warningCount: number;
+ warnings: string[];
+}
+
+/**
+ * Tally an audit result into the counts-only plane. A derivation of the
+ * enumerated plane, never a second determination — same walk, same predicate
+ * (`countDiagnosticsBySource`), only the diagnostic bodies dropped. Callers
+ * that keep file-tree tints fresh want the tallies and would discard the
+ * bodies immediately; on a large KB those bodies are tens of MB per request.
+ */
+export function toValidationCountsPlane(
+ result: ValidationAuditResult,
+): ValidationAuditCountsResult {
+ return {
+ files: result.files.map((entry) => ({
+ file: entry.file,
+ ...countDiagnosticsBySource(entry.diagnostics),
+ })),
+ fileCount: result.fileCount,
+ errorCount: result.errorCount,
+ warningCount: result.warningCount,
+ warnings: result.warnings,
+ };
+}
+
export interface ValidationScope {
/** contentDir-relative folder or doc-file path; absent audits the whole project. */
targetPath?: string;
@@ -80,6 +113,10 @@ export interface ValidationAuditDeps {
admittedDocNames: () => Iterable<string> | Promise<Iterable<string>>;
/** docName → on-disk contentDir-relative path, null when no file exists yet. */
docFilePathFor: (docName: string) => string | null;
+ /** Shared across audits so an unchanged-config re-walk does no lint work. */
+ cache?: AuditCache;
+ /** Lint config + active branch, as one equality token (see `AuditOptions.auditGeneration`). */
+ auditGeneration?: () => string;
}
/**
@@ -105,6 +142,10 @@ export async function runValidationAudit(
try {
return await validator.run(scope);
} catch (error) {
+ // Supersession is not a validator failure — it invalidates the WHOLE
+ // plane, so degrading it to a warning would publish the surviving
+ // validators' findings as if they were a complete answer.
+ if (error instanceof AuditSupersededError) throw error;
// The plane's warning carries only `.message`; the stack goes to the
// server log or a deep validator throw is undebuggable in production.
getLogger('validation-audit').error(
@@ -169,6 +210,8 @@ function createLintValidator(deps: ValidationAuditDeps): ProjectValidator {
baseConfig: deps.baseConfig,
targetPath: scope.targetPath,
liveSourceFor: deps.liveSourceFor,
+ cache: deps.cache,
+ auditGeneration: deps.auditGeneration,
});
return { files: audit.files, fileCount: audit.fileCount, warnings: audit.warnings };
},