Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import {
type ValidationAuditCountsResponse,
ValidationAuditCountsResponseSchema,
type ValidationAuditResponse,
ValidationAuditResponseSchema,
type ValidationDocResult,
} from '@inkeep/open-knowledge-core/markdown/lint';
import type { BrokenLinkSuppression } from '@inkeep/open-knowledge-core/schemas/api';
import { useEffect, useState } from 'react';
import type { z } from 'zod';
import { invalidatesLocalTargetAudit, subscribeToDocumentsChanged } from '@/lib/documents-events';
import { subscribeToLintConfigChanged } from './lint-config-client';
type WireDiagnostic = ValidationDocResult['diagnostics'][number];
export type AuditScope =
| { kind: 'project' }
| { kind: 'path'; path: string }
| { kind: 'doc'; docName: string };
export const AUDIT_SUPERSEDED = 'audit-superseded' as const;
export async function runValidationAudit(
scope: AuditScope = { kind: 'project' },
signal?: AbortSignal,
): Promise<ValidationAuditResponse | null | typeof AUDIT_SUPERSEDED> {
return fetchAudit(scope, ValidationAuditResponseSchema, false, signal);
}
export async function runValidationAuditCounts(
scope: AuditScope = { kind: 'project' },
signal?: AbortSignal,
): Promise<ValidationAuditCountsResponse | null | typeof AUDIT_SUPERSEDED> {
return fetchAudit(scope, ValidationAuditCountsResponseSchema, true, signal);
}
async function fetchAudit<T>(
scope: AuditScope,
schema: z.ZodType<T>,
counts: boolean,
signal?: AbortSignal,
): Promise<T | null | typeof AUDIT_SUPERSEDED> {
try {
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) {
if (res.status === 409) return AUDIT_SUPERSEDED;
console.warn('[audit] request failed', res.status, res.statusText);
return null;
}
let body: unknown;
try {
body = await res.json();
} catch {
if (signal?.aborted === true) return null;
console.warn('[audit] response body is not valid JSON');
return null;
}
const parsed = schema.safeParse(body);
if (!parsed.success) {
console.warn('[audit] response failed schema validation', parsed.error.issues);
return null;
}
return parsed.data;
} catch (err) {
if (signal?.aborted === true) return null;
console.warn('[audit] fetch threw', err);
return null;
}
}
interface DocLinkFindingsSnapshot {
findings: readonly WireDiagnostic[];
brokenLinkSuppression?: BrokenLinkSuppression;
}
export type DocLinkFindingsState = DocLinkFindingsSnapshot & {
status: 'idle' | 'loading' | 'loaded' | 'failed';
};
export function subscribeToDocLinkFindings(
docName: string,
onState: (state: DocLinkFindingsState) => void,
): () => void {
let disposed = false;
let inFlight = false;
let dirty = false;
let findings: readonly WireDiagnostic[] = [];
let brokenLinkSuppression: BrokenLinkSuppression | undefined;
let controller: AbortController | null = null;
const snapshot = (): DocLinkFindingsSnapshot => ({
findings,
...(brokenLinkSuppression === undefined ? {} : { brokenLinkSuppression }),
});
const load = (): void => {
if (inFlight) {
dirty = true;
return;
}
inFlight = true;
controller = new AbortController();
onState({ status: 'loading', ...snapshot() });
void runValidationAudit({ kind: 'doc', docName }, controller.signal)
.then((result) => {
if (disposed || controller?.signal.aborted === true) return;
if (result === null) {
onState({ status: 'failed', ...snapshot() });
return;
}
if (result === AUDIT_SUPERSEDED) {
dirty = true;
return;
}
if (dirty) return;
findings = result.files
.flatMap((file) => file.diagnostics)
.filter((diagnostic) => diagnostic.source === 'links');
brokenLinkSuppression = result.brokenLinkSuppression;
onState({ status: 'loaded', ...snapshot() });
})
.finally(() => {
if (disposed) return;
inFlight = false;
controller = null;
if (dirty) {
dirty = false;
load();
}
});
};
load();
const unsubscribeDocuments = subscribeToDocumentsChanged((channels) => {
if (channels.includes('backlinks') || invalidatesLocalTargetAudit(channels)) load();
});
const unsubscribeLintConfig = subscribeToLintConfigChanged(load);
return () => {
disposed = true;
controller?.abort();
unsubscribeDocuments();
unsubscribeLintConfig();
};
}
export function useDocLinkFindings(docName: string | null): DocLinkFindingsState {
const [owned, setOwned] = useState<{
docName: string | null;
state: DocLinkFindingsState;
}>({ docName: null, state: { status: 'idle', findings: [] } });
useEffect(() => {
if (docName === null) {
setOwned({ docName: null, state: { status: 'idle', findings: [] } });
return;
}
setOwned({ docName, state: { status: 'loading', findings: [] } });
return subscribeToDocLinkFindings(docName, (state) => setOwned({ docName, state }));
}, [docName]);
if (owned.docName !== docName) {
return docName === null
? { status: 'idle', findings: [] }
: { status: 'loading', findings: [] };
}
return owned.state;
}