Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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 thediff --git a/packages/app/src/components/ValidationFreshness.dom.test.tsx b/packages/app/src/components/ValidationFreshness.dom.test.tsxindex 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.tsxindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 };},