Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Give the audit-supersession tests a server-observable settlement barrier (#4883)

Nick Gomez110c4e40de8e
diff --git a/packages/app/tests/integration/audit-barrier.test-helper.ts b/packages/app/tests/integration/audit-barrier.test-helper.ts
new file mode 100644
index 000000000..1107925ea
--- /dev/null
+++ b/packages/app/tests/integration/audit-barrier.test-helper.ts
@@ -0,0 +1,60 @@
+import * as core from '@inkeep/open-knowledge-core';
+import { vi } from 'vitest';
+import { pollUntil } from './test-harness.ts';
+
+const BARRIER_ARRIVAL_TIMEOUT_MS = 20_000;
+
+export interface AuditBarrier {
+ waitUntilStarted(timeoutMs?: number): Promise<void>;
+ release(): void;
+ dispose(): void;
+ observedDocuments(): readonly string[];
+}
+
+export function pauseAuditAtDocument(docRelPath: string): AuditBarrier {
+ if (vi.isMockFunction(core.lintDocument)) {
+ throw new Error(
+ `pauseAuditAtDocument(${docRelPath}): core.lintDocument is already mocked. ` +
+ 'Only one barrier may be live at a time; dispose the previous one first.',
+ );
+ }
+ let arrived = false;
+ const observed: string[] = [];
+ const resume = Promise.withResolvers<void>();
+ const lintDocument = core.lintDocument;
+ const spy = vi
+ .spyOn(core, 'lintDocument')
+ .mockImplementation(async (text, config, docName, ...rest) => {
+ if (docName !== undefined) observed.push(docName);
+ if (docName === docRelPath) {
+ arrived = true;
+ await resume.promise;
+ }
+ return lintDocument(text, config, docName, ...rest);
+ });
+ return {
+ waitUntilStarted(timeoutMs = BARRIER_ARRIVAL_TIMEOUT_MS) {
+ return pollUntil(
+ () => arrived,
+ timeoutMs,
+ 10,
+ `the server-side audit walk to enter lintDocument for ${docRelPath}`,
+ );
+ },
+ release() {
+ if (!arrived) {
+ throw new Error(
+ `release() before the server-side audit walk entered lintDocument for ${docRelPath}`,
+ );
+ }
+ resume.resolve();
+ },
+ dispose() {
+ resume.resolve();
+ spy.mockRestore();
+ },
+ observedDocuments() {
+ return [...observed];
+ },
+ };
+}
diff --git a/packages/app/tests/integration/audit-branch-generation.test.ts b/packages/app/tests/integration/audit-branch-generation.test.ts
index 3a5469634..acd1f8953 100644
--- a/packages/app/tests/integration/audit-branch-generation.test.ts
+++ b/packages/app/tests/integration/audit-branch-generation.test.ts
@@ -2,6 +2,7 @@ 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 { type AuditBarrier, pauseAuditAtDocument } from './audit-barrier.test-helper.ts';
import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
import { createTestServer, type TestServer } from './test-harness.ts';
@@ -56,25 +57,25 @@ describe('GET /api/audit across a branch switch', () => {
async () => {
const folder = join(server.contentDir, SCOPE);
writeCorpus(folder, '\t');
+ let auditBarrier: AuditBarrier | undefined;
try {
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;
- });
+ auditBarrier = pauseAuditAtDocument(`${SCOPE}/doc-1.md`);
+ const first = auditScope();
+ await auditBarrier.waitUntilStarted();
expect((await fetch(api('/api/lint/config'))).status).toBe(200);
- writeCorpus(folder, ' ');
const { durabilityState } = server.instance;
expect(durabilityState.getActiveBranch()).not.toBe('audit-branch-target');
durabilityState.switchReconciledBaseScope('audit-branch-target');
- expect(firstSettled).toBe(false);
+ auditBarrier.release();
+
+ writeCorpus(folder, ' ');
const after = await auditScope();
expect(after.status).toBe(200);
@@ -87,6 +88,7 @@ describe('GET /api/audit across a branch switch', () => {
const problem = (await firstRes.json()) as { type?: string };
expect(problem.type).toBe('urn:ok:error:audit-superseded');
} finally {
+ auditBarrier?.dispose();
rmSync(folder, { recursive: true, force: true });
}
},
diff --git a/packages/app/tests/integration/audit-config-epoch.test.ts b/packages/app/tests/integration/audit-config-epoch.test.ts
index 97fa0ee04..41c17d729 100644
--- a/packages/app/tests/integration/audit-config-epoch.test.ts
+++ b/packages/app/tests/integration/audit-config-epoch.test.ts
@@ -8,6 +8,7 @@ import {
} from '@inkeep/open-knowledge-core';
import { afterAll, beforeAll, describe, expect, test } from 'vitest';
import * as Y from 'yjs';
+import { type AuditBarrier, pauseAuditAtDocument } from './audit-barrier.test-helper.ts';
import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
import {
awaitBacklinkIndexed,
@@ -77,16 +78,15 @@ describe('GET /api/audit across a lint-config change', () => {
const folder = join(server.contentDir, SCOPE);
const nativeFile = join(server.contentDir, '.markdownlint.json');
seedTabbedCorpus(folder);
+ let auditBarrier: AuditBarrier | undefined;
try {
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;
- });
+ auditBarrier = pauseAuditAtDocument(`${SCOPE}/doc-1.md`);
+ const first = auditScope();
+ await auditBarrier.waitUntilStarted();
const write = await fetch(api('/api/lint/markdownlint-config'), {
method: 'POST',
@@ -94,7 +94,7 @@ describe('GET /api/audit across a lint-config change', () => {
body: JSON.stringify({ ruleId: 'MD010', value: false }),
});
expect(write.status).toBe(200);
- expect(firstSettled).toBe(false);
+ auditBarrier.release();
const after = await auditScope();
expect(after.status).toBe(200);
@@ -105,6 +105,7 @@ describe('GET /api/audit across a lint-config change', () => {
const problem = (await firstRes.json()) as { type?: string };
expect(problem.type).toBe('urn:ok:error:audit-superseded');
} finally {
+ auditBarrier?.dispose();
rmSync(folder, { recursive: true, force: true });
rmSync(nativeFile, { force: true });
}
@@ -128,6 +129,7 @@ describe('GET /api/audit across a lint-config change', () => {
connect: true,
});
const binding = bindConfigDoc(provider, 'project');
+ let auditBarrier: AuditBarrier | undefined;
try {
await pollUntil(
@@ -149,7 +151,9 @@ describe('GET /api/audit across a lint-config change', () => {
beforeBody.files.flatMap((file) => file.diagnostics).some((d) => d.code === 'dead-link'),
).toBe(false);
+ auditBarrier = pauseAuditAtDocument(`${SCOPE}/doc-1.md`);
const first = auditScope();
+ await auditBarrier.waitUntilStarted();
const patch = binding.patch({ validation: { suppressLogLinkAdvisories: false } });
expect(patch.ok).toBe(true);
@@ -159,6 +163,7 @@ describe('GET /api/audit across a lint-config change', () => {
25,
'the project config change to reach disk',
);
+ auditBarrier.release();
const firstRes = await first;
expect(firstRes.status).toBe(409);
@@ -190,6 +195,7 @@ describe('GET /api/audit across a lint-config change', () => {
?.diagnostics.some((diagnostic) => diagnostic.code === 'dead-link'),
).toBe(true);
} finally {
+ auditBarrier?.dispose();
binding.dispose();
provider.destroy();
ydoc.destroy();
@@ -208,12 +214,10 @@ describe('GET /api/audit across a lint-config change', () => {
seedTabbedCorpus(folder);
mkdirSync(join(server.contentDir, '.ok', 'schemas'), { recursive: true });
writeFileSync(schemaPath, JSON.stringify({ type: 'object', properties: {} }), 'utf-8');
+ const auditBarrier = pauseAuditAtDocument(`${scope}/doc-1.md`);
try {
- let firstSettled = false;
- const first = auditScope(scope).then((res) => {
- firstSettled = true;
- return res;
- });
+ const first = auditScope(scope);
+ await auditBarrier.waitUntilStarted();
const write = await fetch(api('/api/lint/frontmatter-schema'), {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
@@ -224,7 +228,7 @@ describe('GET /api/audit across a lint-config change', () => {
}),
});
expect(write.status).toBe(200);
- expect(firstSettled).toBe(false);
+ auditBarrier.release();
const firstRes = await first;
expect(firstRes.status).toBe(409);
@@ -245,6 +249,7 @@ describe('GET /api/audit across a lint-config change', () => {
),
).toBe(true);
} finally {
+ auditBarrier.dispose();
rmSync(folder, { recursive: true, force: true });
rmSync(schemaPath, { force: true });
}
@@ -261,12 +266,10 @@ describe('GET /api/audit across a lint-config change', () => {
const brokenConfig = join(server.contentDir, '.markdownlint.json');
const blockedSchemaParent = join(server.contentDir, 'blocked-schema-parent');
seedTabbedCorpus(folder);
+ const auditBarrier = pauseAuditAtDocument(`${scope}/doc-1.md`);
try {
- let firstSettled = false;
- const first = auditScope(scope).then((res) => {
- firstSettled = true;
- return res;
- });
+ const first = auditScope(scope);
+ await auditBarrier.waitUntilStarted();
writeFileSync(executableConfig, 'module.exports = { MD012: false };\n', 'utf-8');
const declined = await fetch(api('/api/lint/markdownlint-config'), {
method: 'POST',
@@ -298,11 +301,12 @@ describe('GET /api/audit across a lint-config change', () => {
body: JSON.stringify({ file: 'blocked-schema-parent/failure.schema.json' }),
});
expect(failedFrontmatter.status).toBe(500);
- expect(firstSettled).toBe(false);
+ auditBarrier.release();
const firstRes = await first;
expect(firstRes.status).toBe(200);
} finally {
+ auditBarrier.dispose();
rmSync(folder, { recursive: true, force: true });
rmSync(executableConfig, { force: true });
rmSync(brokenConfig, { recursive: true, force: true });
diff --git a/packages/app/tests/meta/audit-barrier.test.ts b/packages/app/tests/meta/audit-barrier.test.ts
new file mode 100644
index 000000000..826f90575
--- /dev/null
+++ b/packages/app/tests/meta/audit-barrier.test.ts
@@ -0,0 +1,133 @@
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import * as core from '@inkeep/open-knowledge-core';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import { pauseAuditAtDocument } from '../integration/audit-barrier.test-helper.ts';
+import { HARNESS_BOOT_TIMEOUT_MS } from '../integration/harness-boot-timeout.ts';
+import { createTestServer, type TestServer } from '../integration/test-harness.ts';
+
+let server: TestServer;
+
+const TABBED_SOURCE = '# Title\n\nParagraph with\ta hard tab.\n';
+const DOC_COUNT = 3;
+
+beforeAll(async () => {
+ server = await createTestServer({ markdownlintEnabled: true });
+}, HARNESS_BOOT_TIMEOUT_MS);
+
+afterAll(async () => {
+ await server.cleanup();
+});
+
+function seedScope(scope: string): string {
+ const folder = join(server.contentDir, scope);
+ mkdirSync(folder, { recursive: true });
+ for (let i = 0; i < DOC_COUNT; i += 1) {
+ writeFileSync(join(folder, `doc-${i}.md`), TABBED_SOURCE, 'utf-8');
+ }
+ return folder;
+}
+
+function markdownlintOnConfig(): core.LinterConfig {
+ const base = core.DEFAULT_LINTER_CONFIG;
+ return {
+ ...base,
+ plugins: {
+ ...base.plugins,
+ markdownlint: { ...base.plugins.markdownlint, enabled: true },
+ },
+ };
+}
+
+describe('pauseAuditAtDocument', () => {
+ test('holds the in-process server audit walk inside lintDocument and releases it', async () => {
+ const scope = 'barrier-hold';
+ const folder = seedScope(scope);
+ const original = core.lintDocument;
+ const barrier = pauseAuditAtDocument(`${scope}/doc-1.md`);
+ let status = 0;
+ try {
+ const audit = fetch(`${server.baseUrl}/api/audit?path=${scope}`);
+ await barrier.waitUntilStarted();
+ const observedWhileHeld = barrier.observedDocuments();
+ expect(observedWhileHeld).toContain(`${scope}/doc-0.md`);
+ expect(observedWhileHeld.at(-1)).toBe(`${scope}/doc-1.md`);
+ barrier.release();
+ const res = await audit;
+ status = res.status;
+ await res.text();
+ } finally {
+ barrier.dispose();
+ rmSync(folder, { recursive: true, force: true });
+ }
+ expect(status).toBe(200);
+ expect(core.lintDocument).toBe(original);
+ });
+
+ test('does not fire for a document the audit never visits, and names that document when it gives up', async () => {
+ const scope = 'barrier-miss';
+ const folder = seedScope(scope);
+ const original = core.lintDocument;
+ const barrier = pauseAuditAtDocument('never-visited/doc.md');
+ try {
+ const res = await fetch(`${server.baseUrl}/api/audit?path=${scope}`);
+ expect(res.status).toBe(200);
+ await res.text();
+ expect(barrier.observedDocuments()).toContain(`${scope}/doc-1.md`);
+ await expect(barrier.waitUntilStarted(50)).rejects.toThrow(
+ 'the server-side audit walk to enter lintDocument for never-visited/doc.md',
+ );
+ } finally {
+ barrier.dispose();
+ rmSync(folder, { recursive: true, force: true });
+ }
+ expect(core.lintDocument).toBe(original);
+ });
+
+ test('refuses a release that comes before the audit walk reaches the held document', () => {
+ const original = core.lintDocument;
+ const barrier = pauseAuditAtDocument('barrier-early-release/doc.md');
+ try {
+ expect(() => barrier.release()).toThrow(
+ 'release() before the server-side audit walk entered lintDocument for barrier-early-release/doc.md',
+ );
+ } finally {
+ barrier.dispose();
+ }
+ expect(core.lintDocument).toBe(original);
+ });
+
+ test('refuses a second barrier while an earlier one is still installed', () => {
+ const original = core.lintDocument;
+ const barrier = pauseAuditAtDocument('barrier-double-install/first.md');
+ try {
+ expect(() => pauseAuditAtDocument('barrier-double-install/second.md')).toThrow(
+ 'already mocked',
+ );
+ } finally {
+ barrier.dispose();
+ }
+ expect(core.lintDocument).toBe(original);
+ });
+
+ test('delegates to the real lintDocument instead of standing in for it', async () => {
+ const config = markdownlintOnConfig();
+ const expected = await core.lintDocument(TABBED_SOURCE, config, 'barrier-delegation/free.md');
+ expect(expected.length).toBeGreaterThan(0);
+
+ const original = core.lintDocument;
+ const barrier = pauseAuditAtDocument('barrier-delegation/held.md');
+ try {
+ const free = await core.lintDocument(TABBED_SOURCE, config, 'barrier-delegation/free.md');
+ expect(free).toEqual(expected);
+
+ const heldCall = core.lintDocument(TABBED_SOURCE, config, 'barrier-delegation/held.md');
+ await barrier.waitUntilStarted();
+ barrier.release();
+ expect(await heldCall).toEqual(expected);
+ } finally {
+ barrier.dispose();
+ }
+ expect(core.lintDocument).toBe(original);
+ });
+});
diff --git a/packages/app/tsconfig.json b/packages/app/tsconfig.json
index 63124f485..5938e4114 100644
--- a/packages/app/tsconfig.json
+++ b/packages/app/tsconfig.json
@@ -72,11 +72,21 @@
// `@playwright/test`, so its closure adds no other file to the program. The
// `.e2e.ts` and `.dom.test.ts` consumers stay outside: the former would pull
// the whole `_helpers` barrel in, and the latter is excluded as `*.test.ts`.
+ //
+ // `tests/integration/audit-barrier.test-helper.ts` is named for the same
+ // reason. `docName` is optional upstream, so pushing it unnarrowed into the
+ // barrier's `string[]` observation list fails as TS2345 rather than
+ // surfacing as an `undefined` at an assertion. The pin stops at the helper:
+ // all three files that import it are `*.test.ts` and stay excluded. It
+ // imports `@inkeep/open-knowledge-core`, `vitest` and
+ // `tests/integration/test-harness.ts`, all of which the entries above
+ // already pull in, so its closure adds no other file to the program.
"include": [
"src",
"*.ts",
"tests/stress/fixtures",
"tests/half-open-forced-close.test-helper.ts",
+ "tests/integration/audit-barrier.test-helper.ts",
"tests/stress/_helpers/acp-catalog.ts",
"tests/stress/_helpers/editor-state.ts",
"tests/stress/_helpers/image.ts",