Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

14.2 KB
Raw Blame
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { resolve } from 'node:path';
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from 'vitest';
import { type Config, ConfigSchema } from '../../config/schema.ts';
import { type FetchTestServer, startFetchTestServer } from './fetch-test-server.test-helper.ts';
import { DESCRIPTION, type LintDeps, register } from './lint.ts';
import type { ServerInstance } from './shared.ts';
import { AUDIT_FILE_CAP, AUDIT_FILE_DIAGNOSTIC_CAP, hocuspocusNotRunningError } from './shared.ts';

const BASE_CONFIG: Config = ConfigSchema.parse({});

interface ToolResult {
  content: Array<{ type: 'text'; text: string }>;
  structuredContent?: Record<string, unknown>;
  isError?: boolean;
}

interface LintHandlerArgs {
  document?: string;
  path?: string;
  fix?: boolean;
}

interface RegisteredTool {
  name: string;
  description: string;
  annotations?: Record<string, unknown>;
  handler: (args: LintHandlerArgs, signal?: AbortSignal) => Promise<ToolResult>;
}

function createFakeServer() {
  let registered: RegisteredTool | undefined;
  const server = {
    registerTool(
      name: string,
      cfg: { description?: string; annotations?: Record<string, unknown> },
      handler: (args: LintHandlerArgs, extra: { signal: AbortSignal }) => Promise<ToolResult>,
    ) {
      registered = {
        name,
        description: cfg.description ?? '',
        annotations: cfg.annotations,
        handler: (args, signal = new AbortController().signal) => handler(args, { signal }),
      };
    },
  } as unknown as ServerInstance;
  return {
    server,
    getTool(): RegisteredTool {
      if (!registered) throw new Error('Tool was not registered');
      return registered;
    },
  };
}

function makeDeps(serverUrl: string | undefined, cwdDir: string): LintDeps {
  return { serverUrl, config: BASE_CONFIG, resolveCwd: async () => cwdDir };
}

test('project-wide lint honors the MCP request cancellation signal', async () => {
  const { server, getTool } = createFakeServer();
  register(server, makeDeps(baseUrl, tmpDir));
  const signal = AbortSignal.abort(new DOMException('Caller deadline expired', 'TimeoutError'));

  const result = await getTool().handler({}, signal);

  expect(result.isError).toBe(true);
  expect(result.content[0]?.text).toContain('Caller deadline expired');
});

let testServer: FetchTestServer;
let baseUrl: string;
let tmpDir: string;
const seenRequests: string[] = [];

function warningDiagnostic(line: number) {
  return {
    range: { start: { line, character: 0 }, end: { line, character: 1 } },
    severity: 'warning',
    source: 'markdownlint',
    code: 'MD010',
    message: 'Hard tabs',
  };
}

function auditPayloadOf(fileCount: number, diagnosticsPerFile: number) {
  const files = Array.from({ length: fileCount }, (_, i) => ({
    file: `doc-${String(i).padStart(2, '0')}.md`,
    diagnostics: Array.from({ length: diagnosticsPerFile }, (_, line) => warningDiagnostic(line)),
  }));
  return {
    ok: true,
    files,
    fileCount,
    errorCount: 0,
    warningCount: fileCount * diagnosticsPerFile,
    warnings: [],
  };
}

beforeAll(async () => {
  testServer = await startFetchTestServer({
    port: 0,
    hostname: '127.0.0.1',
    fetch(req) {
      const url = new URL(req.url);
      seenRequests.push(`${url.pathname}?${url.searchParams.toString()}`);
      if (url.pathname === '/api/lint/fix') {
        return Response.json({
          ok: true,
          file: 'notes.md',
          fixedCount: 2,
          diagnostics: [
            {
              range: { start: { line: 4, character: 0 }, end: { line: 4, character: 5 } },
              severity: 'warning',
              source: 'markdownlint',
              code: 'MD041',
              message: 'First line in file should be a top-level heading',
            },
          ],
          errorCount: 0,
          warningCount: 1,
        });
      }
      if (url.pathname === '/api/lint') {
        const doc = url.searchParams.get('doc');
        if (doc === 'clean') return Response.json({ ok: true, file: 'clean.md', diagnostics: [] });
        if (doc === 'fixable') {
          return Response.json({
            ok: true,
            file: 'fixable.md',
            diagnostics: [
              {
                range: { start: { line: 2, character: 0 }, end: { line: 2, character: 1 } },
                severity: 'warning',
                source: 'markdownlint',
                code: 'MD010',
                message: 'Hard tabs',
                fixes: [
                  {
                    range: { start: { line: 2, character: 0 }, end: { line: 2, character: 1 } },
                    newText: '  ',
                  },
                ],
              },
            ],
          });
        }
        return Response.json({
          ok: true,
          file: `${doc}.md`,
          diagnostics: [
            {
              range: { start: { line: 2, character: 0 }, end: { line: 2, character: 1 } },
              severity: 'warning',
              source: 'markdownlint',
              code: 'MD010',
              message: 'Hard tabs',
            },
          ],
        });
      }
      if (url.pathname === '/api/lint/audit') {
        const path = url.searchParams.get('path');
        if (path === 'over-cap') {
          return Response.json(auditPayloadOf(AUDIT_FILE_CAP + 2, AUDIT_FILE_DIAGNOSTIC_CAP + 3));
        }
        if (path === 'at-cap') {
          return Response.json(auditPayloadOf(AUDIT_FILE_CAP, AUDIT_FILE_DIAGNOSTIC_CAP));
        }
        return Response.json({
          ok: true,
          files: [
            {
              file: 'dirty.md',
              diagnostics: [
                {
                  range: { start: { line: 2, character: 0 }, end: { line: 2, character: 1 } },
                  severity: 'warning',
                  source: 'markdownlint',
                  code: 'MD010',
                  message: 'Hard tabs',
                },
                {
                  range: { start: { line: 0, character: 0 }, end: { line: 0, character: 3 } },
                  severity: 'error',
                  source: 'frontmatter',
                  code: 'required',
                  message: 'Missing required property: title',
                },
              ],
            },
          ],
          fileCount: 4,
          errorCount: 1,
          warningCount: 1,
          warnings: [],
        });
      }
      return Response.json({ ok: false, error: 'Not found' }, { status: 404 });
    },
  });
  baseUrl = `http://127.0.0.1:${testServer.port}`;
});

afterAll(() => {
  testServer.stop();
});

beforeEach(async () => {
  tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-lint-test-'));
  seenRequests.length = 0;
});

afterEach(async () => {
  await rm(tmpDir, { recursive: true, force: true });
});

describe('lint — registration + DESCRIPTION', () => {
  test('registers exactly one tool named "lint"', () => {
    const { server, getTool } = createFakeServer();
    register(server, makeDeps(baseUrl, tmpDir));
    expect(getTool().name).toBe('lint');
  });

  test('declares mutating (fix-capable) tool annotations', () => {
    const { server, getTool } = createFakeServer();
    register(server, makeDeps(baseUrl, tmpDir));
    expect(getTool().annotations).toEqual({
      readOnlyHint: false,
      destructiveHint: false,
      idempotentHint: true,
    });
  });

  test('DESCRIPTION documents both shapes and the fix mode', () => {
    expect(DESCRIPTION).toContain('`document`');
    expect(DESCRIPTION).toContain('audit');
    expect(DESCRIPTION).toContain('severity');
    expect(DESCRIPTION).toContain('`fix: true`');
  });

  test('returns Hocuspocus-unavailable error when no serverUrl is configured', async () => {
    const { server, getTool } = createFakeServer();
    register(server, makeDeps(undefined, tmpDir));
    const result = await getTool().handler({});
    expect(result.isError).toBe(true);
    expect(result.content[0]?.text).toBe(hocuspocusNotRunningError());
  });
});

describe('lint — single document', () => {
  test('hits /api/lint with a normalized docName and returns its diagnostics', async () => {
    const { server, getTool } = createFakeServer();
    register(server, makeDeps(baseUrl, tmpDir));
    const result = await getTool().handler({ document: 'notes.md' });
    expect(seenRequests).toContain('/api/lint?doc=notes');
    const s = result.structuredContent as {
      files: Array<{ file: string; diagnostics: unknown[] }>;
      errorCount: number;
      warningCount: number;
    };
    expect(s.files).toHaveLength(1);
    expect(s.files[0]?.diagnostics).toHaveLength(1);
    expect(s.errorCount).toBe(0);
    expect(s.warningCount).toBe(1);
    expect(result.content[0]?.text).toContain('markdownlint/MD010');
    expect(result.content[0]?.text).toContain('line 3');
  });

  test('a clean doc reports no problems', async () => {
    const { server, getTool } = createFakeServer();
    register(server, makeDeps(baseUrl, tmpDir));
    const result = await getTool().handler({ document: 'clean' });
    const s = result.structuredContent as { warningCount: number; errorCount: number };
    expect(s.warningCount).toBe(0);
    expect(s.errorCount).toBe(0);
    expect(result.content[0]?.text).toContain('No problems');
  });
});

describe('lint — project audit', () => {
  test('omitting document hits /api/lint/audit and summarizes counts', async () => {
    const { server, getTool } = createFakeServer();
    register(server, makeDeps(baseUrl, tmpDir));
    const result = await getTool().handler({});
    expect(seenRequests.some((r) => r.startsWith('/api/lint/audit'))).toBe(true);
    const s = result.structuredContent as {
      files: unknown[];
      fileCount: number;
      errorCount: number;
      warningCount: number;
    };
    expect(s.files).toHaveLength(1);
    expect(s.fileCount).toBe(4);
    expect(s.errorCount).toBe(1);
    expect(s.warningCount).toBe(1);
    expect(result.content[0]?.text).toContain('dirty.md');
    expect(result.content[0]?.text).toContain('1 error');
  });

  test('passes a sub-path scope through to the audit endpoint', async () => {
    const { server, getTool } = createFakeServer();
    register(server, makeDeps(baseUrl, tmpDir));
    await getTool().handler({ path: 'sub/dir' });
    expect(seenRequests).toContain('/api/lint/audit?path=sub%2Fdir');
  });
});

describe('lint — audit output cap', () => {
  interface AuditStructured {
    files: Array<{
      file: string;
      diagnostics: unknown[];
      omittedDiagnosticCount?: number;
    }>;
    fileCount: number;
    errorCount: number;
    warningCount: number;
    omittedFileCount?: number;
  }

  test('over-cap audits truncate both channels but keep totals accurate', async () => {
    const { server, getTool } = createFakeServer();
    register(server, makeDeps(baseUrl, tmpDir));
    const result = await getTool().handler({ path: 'over-cap' });

    const s = result.structuredContent as unknown as AuditStructured;
    expect(s.files).toHaveLength(AUDIT_FILE_CAP);
    expect(s.omittedFileCount).toBe(2);
    for (const file of s.files) {
      expect(file.diagnostics).toHaveLength(AUDIT_FILE_DIAGNOSTIC_CAP);
      expect(file.omittedDiagnosticCount).toBe(3);
    }
    expect(s.fileCount).toBe(AUDIT_FILE_CAP + 2);
    expect(s.warningCount).toBe((AUDIT_FILE_CAP + 2) * (AUDIT_FILE_DIAGNOSTIC_CAP + 3));

    const text = result.content[0]?.text ?? '';
    expect(text).toContain(`${AUDIT_FILE_CAP + 2} of ${AUDIT_FILE_CAP + 2} documents`);
    expect(text).toContain('… and 3 more problems');
    expect(text).toContain('lint({ document: "doc-00.md" })');
    expect(text).toContain('all document lint findings');
    expect(text).toContain('… and 2 more files with problems');
    expect(text).toContain('Narrow path to reduce competing files; per-file caps still apply');
    const shownFileHeaders = text.match(/^doc-\d+\.md:$/gm) ?? [];
    expect(shownFileHeaders).toHaveLength(AUDIT_FILE_CAP);
  });

  test('an audit exactly at the cap is complete, with no truncation indicators', async () => {
    const { server, getTool } = createFakeServer();
    register(server, makeDeps(baseUrl, tmpDir));
    const result = await getTool().handler({ path: 'at-cap' });

    const s = result.structuredContent as unknown as AuditStructured;
    expect(s.files).toHaveLength(AUDIT_FILE_CAP);
    expect(s.omittedFileCount).toBeUndefined();
    for (const file of s.files) {
      expect(file.diagnostics).toHaveLength(AUDIT_FILE_DIAGNOSTIC_CAP);
      expect(file.omittedDiagnosticCount).toBeUndefined();
    }

    const text = result.content[0]?.text ?? '';
    expect(text).not.toContain('… and');
  });
});

describe('lint — fix mode', () => {
  test('fix:true POSTs /api/lint/fix and reports fixed + remaining', async () => {
    const { server, getTool } = createFakeServer();
    register(server, makeDeps(baseUrl, tmpDir));
    const result = await getTool().handler({ document: 'notes.md', fix: true });
    expect(seenRequests.some((r) => r.startsWith('/api/lint/fix'))).toBe(true);
    const s = result.structuredContent as {
      fixedCount: number;
      files: Array<{ diagnostics: unknown[] }>;
      warningCount: number;
    };
    expect(s.fixedCount).toBe(2);
    expect(s.files[0]?.diagnostics).toHaveLength(1);
    const text = result.content[0]?.text ?? '';
    expect(text).toContain('Fixed 2 problems in notes.md');
    expect(text).toContain('1 problem remain');
    expect(text).toContain('`edit`/`write`');
  });

  test('fix:true without a document is an error and hits no endpoint', async () => {
    const { server, getTool } = createFakeServer();
    register(server, makeDeps(baseUrl, tmpDir));
    const result = await getTool().handler({ fix: true });
    expect(result.isError).toBe(true);
    expect(result.content[0]?.text).toContain('requires `document`');
    expect(seenRequests.some((r) => r.startsWith('/api/lint/fix'))).toBe(false);
  });
});

describe('lint — fixability hint', () => {
  test('a single-doc report quantifies how many violations `fix: true` would resolve', async () => {
    const { server, getTool } = createFakeServer();
    register(server, makeDeps(baseUrl, tmpDir));
    const result = await getTool().handler({ document: 'fixable' });
    const text = result.content[0]?.text ?? '';
    expect(text).toContain('auto-fixable');
    expect(text).toContain('`fix: true`');
  });
});