Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
import { dirname, join, relative, sep } from 'node:path';
import {
AUDIT_EMPTY_SCOPE_WARNING,
deriveValidationRunSources,
fixDocument,
type LintDiagnostic,
type LinterConfig,
type LintPluginFailure,
type LintPluginId,
lintDocument,
SUPPORTED_DOC_EXTENSIONS,
summarizeLintPluginFailures,
} from '@inkeep/open-knowledge-core';
import { atomicTempPath } from '@inkeep/open-knowledge-core/server';
import {
type AuditScope,
composeEffectiveLinterConfig,
composeFrontmatterSchemasConfig,
createContentFilter,
resolveAuditScope,
resolveNativeConfigForDoc,
} from '@inkeep/open-knowledge-server';
interface FileLintResult {
file: string;
diagnostics: LintDiagnostic[];
fixed: boolean;
}
export interface LintRunResult {
contentDir: string;
files: FileLintResult[];
warnings: string[];
fileCount: number;
errorCount: number;
warningCount: number;
fixedCount: number;
ran: LintPluginId[];
}
export interface RunLintOptions {
projectDir: string;
contentDir: string;
baseConfig: LinterConfig;
targetPath?: string;
resolvedScope?: AuditScope;
fix?: boolean;
}
export async function runLint(opts: RunLintOptions): Promise<LintRunResult> {
const { projectDir, contentDir, baseConfig, targetPath, fix = false } = opts;
const resolution =
opts.resolvedScope === undefined
? resolveAuditScope(targetPath, contentDir)
: { ok: true as const, scope: opts.resolvedScope };
if (!resolution.ok) throw new Error(resolution.title);
const scope = resolution.scope;
const warnings: string[] = [];
const filter = createContentFilter({ projectDir, contentDir });
const seenConfigProblems = new Set<string>();
const pushConfigProblem = (problem: string): void => {
if (seenConfigProblems.has(problem)) return;
seenConfigProblems.add(problem);
warnings.push(problem);
};
const resolvedBase = composeFrontmatterSchemasConfig(projectDir, baseConfig, pushConfigProblem);
const ran = deriveValidationRunSources(resolvedBase, { mode: 'lint' });
const pluginFailures: LintPluginFailure[] = [];
const pushPluginFailure = (failure: LintPluginFailure): void => {
pluginFailures.push(failure);
};
const cfgByDir = new Map<string, LinterConfig>();
const configForDoc = (rel: string): LinterConfig => {
const dir = dirname(rel);
const cached = cfgByDir.get(dir);
if (cached) return cached;
const native = resolveNativeConfigForDoc(contentDir, rel, pushConfigProblem);
const cfg = composeEffectiveLinterConfig(resolvedBase, native);
cfgByDir.set(dir, cfg);
return cfg;
};
const docFiles: string[] = [];
let scanIncomplete = false;
const scopeRel = relative(contentDir, scope.path);
const explicitHidden = scopeRel
.split(sep)
.some((segment) => segment.startsWith('.') && segment !== '..');
if (scope.kind === 'file') {
docFiles.push(scopeRel);
} else if (scopeRel === '' || explicitHidden || !filter.isDirExcluded(scopeRel)) {
walk(scope.path);
}
function walk(absDir: string): void {
let entries: import('node:fs').Dirent[];
try {
entries = readdirSync(absDir, { withFileTypes: true });
} catch (e) {
scanIncomplete = true;
warnings.push(
`could not read directory ${relative(contentDir, absDir) || '.'}: ${errMsg(e)}`,
);
return;
}
for (const entry of entries) {
if (entry.name.startsWith('.')) continue;
const full = join(absDir, entry.name);
const rel = relative(contentDir, full);
if (entry.isDirectory()) {
if (filter.isDirExcluded(rel)) continue;
walk(full);
} else if (entry.isFile()) {
if (!isDocFile(entry.name)) continue;
if (filter.isExcluded(rel)) continue;
docFiles.push(rel);
}
}
}
docFiles.sort();
if (docFiles.length === 0 && !scanIncomplete) warnings.push(AUDIT_EMPTY_SCOPE_WARNING);
const files: FileLintResult[] = [];
let errorCount = 0;
let warningCount = 0;
let fixedCount = 0;
for (const rel of docFiles) {
const abs = join(contentDir, rel);
let text: string;
try {
text = readFileSync(abs, 'utf-8');
} catch (e) {
warnings.push(`could not read ${rel}: ${errMsg(e)}`);
continue;
}
const cfg = configForDoc(rel);
let wasFixed = false;
if (fix && cfg.enabled) {
const fixedText = fixDocument(text, cfg, rel, pushPluginFailure);
if (fixedText !== text) {
const tmp = atomicTempPath(abs);
try {
writeFileSync(tmp, fixedText, 'utf-8');
renameSync(tmp, abs);
text = fixedText;
wasFixed = true;
fixedCount++;
} catch (e) {
try {
unlinkSync(tmp);
} catch {}
warnings.push(`could not write fix to ${rel}: ${errMsg(e)}`);
}
}
}
const diagnostics = await lintDocument(text, cfg, rel, pushPluginFailure);
for (const d of diagnostics) {
if (d.severity === 'error') errorCount++;
else warningCount++;
}
files.push({ file: rel, diagnostics, fixed: wasFixed });
}
warnings.push(...summarizeLintPluginFailures(pluginFailures));
return {
contentDir,
files,
warnings,
fileCount: docFiles.length,
errorCount,
warningCount,
fixedCount,
ran,
};
}
function isDocFile(name: string): boolean {
const lower = name.toLowerCase();
return SUPPORTED_DOC_EXTENSIONS.some((ext) => lower.endsWith(ext));
}
function errMsg(e: unknown): string {
return e instanceof Error ? e.message : String(e);
}