Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

12.0 KB
Raw Blame
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { hostname, tmpdir } from 'node:os';
import { join } from 'node:path';
import type { ValidationAuditResponse } from '@inkeep/open-knowledge-core';
import type { Config } from '@inkeep/open-knowledge-server';
import { RUNTIME_VERSION } from '@inkeep/open-knowledge-server';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { runAudit, toContentRelativeTarget } from './audit.ts';

beforeEach(() => {
  vi.stubEnv('OK_CHANNEL', 'stable');
});

afterEach(() => {
  vi.unstubAllEnvs();
});

const minimalConfig = { content: { dir: '.' } } as Config;

function payload(over: Partial<ValidationAuditResponse> = {}): ValidationAuditResponse {
  return {
    files: [],
    fileCount: 0,
    errorCount: 0,
    warningCount: 0,
    warnings: [],
    ...over,
  };
}

function diagnostic(over: Record<string, unknown> = {}) {
  return {
    range: { start: { line: 2, character: 0 }, end: { line: 2, character: 1 } },
    severity: 'warning' as const,
    source: 'markdownlint',
    code: 'MD010',
    message: 'Hard tabs',
    ...over,
  };
}

function imageDiagnostic() {
  return diagnostic({
    range: { start: { line: 5, character: 2 }, end: { line: 5, character: 2 } },
    source: 'links',
    code: 'dead-link',
    message: 'Image target "./logo.png" does not resolve to an existing file.',
    localTarget: {
      href: './logo.png',
      targetKind: 'file',
      role: 'image',
      sourceForm: 'markdown-inline',
      resolvedTarget: 'assets/logo.png',
      reason: 'no-such-file',
      resolutionMethod: 'source-relative',
    },
  });
}

function collectIo() {
  const out: string[] = [];
  const err: string[] = [];
  return {
    io: { out: (l: string) => out.push(l), err: (l: string) => err.push(l) },
    out,
    err,
  };
}

describe('toContentRelativeTarget', () => {
  const contentDir = '/home/user/project';

  test('joins a relative path onto the invocation cwd and relativizes', () => {
    expect(toContentRelativeTarget('guides/intro.md', contentDir, contentDir)).toBe(
      'guides/intro.md',
    );
  });

  test('resolves from a nested invocation cwd', () => {
    expect(toContentRelativeTarget('intro.md', join(contentDir, 'guides'), contentDir)).toBe(
      'guides/intro.md',
    );
  });

  test('normalizes a leading-dot path', () => {
    expect(toContentRelativeTarget('./guides', contentDir, contentDir)).toBe('guides');
  });

  test('returns empty string for the content dir itself', () => {
    expect(toContentRelativeTarget('.', contentDir, contentDir)).toBe('');
  });

  test('rejects a path escaping the content dir', () => {
    expect(toContentRelativeTarget('../outside', contentDir, contentDir)).toBeNull();
    expect(toContentRelativeTarget('/etc/passwd', contentDir, contentDir)).toBeNull();
  });
});

describe('runAudit', () => {
  const origFetch = globalThis.fetch;
  let dir: string;

  beforeEach(() => {
    dir = mkdtempSync(join(tmpdir(), 'ok-audit-test-'));
    const lockDir = join(dir, '.ok', 'local');
    mkdirSync(lockDir, { recursive: true });
    writeFileSync(
      join(lockDir, 'server.lock'),
      JSON.stringify({ pid: process.pid, hostname: hostname(), port: 54321 }),
    );
  });

  afterEach(() => {
    globalThis.fetch = origFetch;
    rmSync(dir, { recursive: true, force: true });
  });

  function stubFetch(
    body: unknown,
    status = 200,
  ): { urls: string[]; inits: (RequestInit | undefined)[] } {
    const urls: string[] = [];
    const inits: (RequestInit | undefined)[] = [];
    globalThis.fetch = (async (url: RequestInfo | URL, init?: RequestInit) => {
      urls.push(String(url));
      inits.push(init);
      return new Response(JSON.stringify(body), {
        status,
        headers: { 'content-type': 'application/json' },
      });
    }) as typeof fetch;
    return { urls, inits };
  }

  test('clean audit: GET /api/audit with cli version headers, exit 0', async () => {
    const { urls, inits } = stubFetch(payload({ fileCount: 3, ran: ['markdownlint', 'links'] }));
    const { io, out } = collectIo();

    const code = await runAudit(undefined, {}, minimalConfig, dir, dir, io);

    expect(code).toBe(0);
    expect(urls[0]).toBe('http://127.0.0.1:54321/api/audit');
    const headers = inits[0]?.headers as Record<string, string>;
    expect(headers['x-ok-client-kind']).toBe('cli');
    expect(headers['x-ok-client-runtime']).toBe(RUNTIME_VERSION);
    expect(out.join('\n')).toContain('No problems in 3 files');
    expect(out.join('\n')).toContain('Checks run: markdownlint, links.');
  });

  test('a filtered clean audit reports reserved-log suppression without exposing links', async () => {
    stubFetch(
      payload({
        fileCount: 3,
        brokenLinkSuppression: { reason: 'reserved-log-policy', count: 2 },
      }),
    );
    const { io, out } = collectIo();

    const code = await runAudit(undefined, {}, minimalConfig, dir, dir, io);

    expect(code).toBe(0);
    const text = out.join('\n');
    expect(text).toContain('2 broken-link findings withheld by project policy');
    expect(text).toContain('audit result is filtered');
    expect(text).toContain('does NOT prove every link resolves');
    expect(text).toContain('http://127.0.0.1:54321/api/dead-links');
    expect(text).toContain('validation.suppressLogLinkAdvisories: false');
    expect(text).toContain('.ok/config.yml');
    expect(text).toContain('Settings ▸ This project ▸ Preferences ▸ Content rules');
    expect(text).not.toContain('links({ kind: "dead" })');
    expect(text).toContain('not as a repair queue');
    expect(text).toContain('protect that history');
    expect(text).not.toContain('the user');
    expect(text).not.toContain('turning the project setting off yourself');
  });

  test('scopes the query to the contentDir-relative target', async () => {
    const { urls } = stubFetch(payload());
    const { io } = collectIo();

    await runAudit('guides/intro.md', {}, minimalConfig, dir, dir, io);

    expect(urls[0]).toBe('http://127.0.0.1:54321/api/audit?path=guides%2Fintro.md');
  });

  test('renders the unified plane with source-tagged rows and exits 1 on problems', async () => {
    stubFetch(
      payload({
        fileCount: 2,
        errorCount: 1,
        warningCount: 1,
        ran: ['markdownlint', 'links'],
        files: [
          {
            file: 'a.md',
            diagnostics: [
              diagnostic(),
              diagnostic({
                severity: 'error',
                source: 'links',
                code: 'dead-link',
                message: 'Link target "missing" does not resolve to an existing document.',
              }),
            ],
          },
        ],
      }),
    );
    const { io, out } = collectIo();

    const code = await runAudit(undefined, {}, minimalConfig, dir, dir, io);

    expect(code).toBe(1);
    const text = out.join('\n');
    expect(text).toContain('a.md');
    expect(text).toContain('markdownlint/MD010');
    expect(text).toContain('links/dead-link');
    expect(text).toContain('2 problems');
    expect(text).toContain('Checks run: markdownlint, links.');
  });

  test('--errors-only ignores warning-severity findings for the exit code', async () => {
    stubFetch(
      payload({
        fileCount: 1,
        warningCount: 1,
        files: [{ file: 'a.md', diagnostics: [diagnostic()] }],
      }),
    );
    const { io } = collectIo();

    const code = await runAudit(undefined, { errorsOnly: true }, minimalConfig, dir, dir, io);

    expect(code).toBe(0);
  });

  test('--json emits the full uncapped payload', async () => {
    const body = payload({
      fileCount: 1,
      warningCount: 1,
      ran: ['markdownlint', 'links'],
      files: [{ file: 'a.md', diagnostics: [diagnostic()] }],
    });
    stubFetch(body);
    const { io, out } = collectIo();

    const code = await runAudit(undefined, { json: true }, minimalConfig, dir, dir, io);

    expect(code).toBe(1);
    expect(JSON.parse(out.join('\n'))).toEqual(body);
  });

  test('--json preserves local-target evidence verbatim', async () => {
    const body = payload({
      fileCount: 1,
      warningCount: 1,
      files: [{ file: 'pics.md', diagnostics: [imageDiagnostic()] }],
    });
    stubFetch(body);
    const { io, out } = collectIo();

    const code = await runAudit(undefined, { json: true }, minimalConfig, dir, dir, io);

    expect(code).toBe(1);
    expect(JSON.parse(out.join('\n'))).toEqual(body);
  });

  test('formatted output points at the occurrence and reads as an image break', async () => {
    stubFetch(
      payload({
        fileCount: 1,
        warningCount: 1,
        files: [{ file: 'pics.md', diagnostics: [imageDiagnostic()] }],
      }),
    );
    const { io, out } = collectIo();

    const code = await runAudit(undefined, {}, minimalConfig, dir, dir, io);

    expect(code).toBe(1);
    const text = out.join('\n');
    expect(text).toContain('6:3');
    expect(text).toContain('links/dead-link');
    expect(text).toContain('Image target "./logo.png" does not resolve to an existing file');
  });

  test('surfaces engine degradation warnings in the report', async () => {
    stubFetch(
      payload({
        warnings: ['source family "links" validation failed: backlink index is not configured'],
      }),
    );
    const { io, out } = collectIo();

    const code = await runAudit(undefined, {}, minimalConfig, dir, dir, io);

    expect(code).toBe(0);
    expect(out.join('\n')).toContain('source family "links" validation failed');
  });

  test('errors with `ok start` guidance when no server lock is live', async () => {
    rmSync(join(dir, '.ok', 'local', 'server.lock'));
    const { io, err } = collectIo();

    const code = await runAudit(undefined, {}, minimalConfig, dir, dir, io);

    expect(code).toBe(1);
    expect(err.join('\n')).toContain('ok start');
    expect(err.join('\n')).toContain('ok lint');
  });

  test.each([
    ['stable', 'ok'],
    ['beta', 'ok-beta'],
  ])('no-server guidance names the %s command', async (channel, command) => {
    vi.stubEnv('OK_CHANNEL', channel);
    rmSync(join(dir, '.ok', 'local', 'server.lock'));
    const { io, err } = collectIo();

    expect(await runAudit(undefined, {}, minimalConfig, dir, dir, io)).toBe(1);
    expect(err.join('\n')).toContain(
      `Start it with \`${command} start\` (or open OK Desktop) and re-run. For headless lint-only checks, use \`${command} lint\`.`,
    );
  });

  test('rejects a target outside the content dir before dialing the server', async () => {
    const { urls } = stubFetch(payload());
    const { io, err } = collectIo();

    const code = await runAudit('../outside', {}, minimalConfig, dir, dir, io);

    expect(code).toBe(1);
    expect(urls).toHaveLength(0);
    expect(err.join('\n')).toContain('outside the content directory');
  });

  test('preserves the full ProblemDetails object in JSON mode', async () => {
    const problem = {
      type: 'urn:ok:error:not-found',
      title: 'Audit scope "missing" was not found. Use an existing file or directory.',
      status: 404,
      instance: 'urn:uuid:ef975a9a-8229-4e36-82a8-2eae23141320',
      detail: 'Server detail survives.',
      recovery: { retryable: false },
    };
    stubFetch(problem, 404);
    const { io, out, err } = collectIo();
    expect(await runAudit('missing', { json: true }, minimalConfig, dir, dir, io)).toBe(1);
    expect(JSON.parse(out.join('\n'))).toEqual(problem);
    expect(err).toEqual([]);
  });

  test('surfaces the problem+json title on a non-OK response', async () => {
    stubFetch({ title: 'Invalid path.' }, 400);
    const { io, err } = collectIo();

    const code = await runAudit(undefined, {}, minimalConfig, dir, dir, io);

    expect(code).toBe(1);
    expect(err.join('\n')).toContain('Invalid path.');
  });

  test('errors on an unexpected response shape', async () => {
    stubFetch({ nonsense: true });
    const { io, err } = collectIo();

    const code = await runAudit(undefined, {}, minimalConfig, dir, dir, io);

    expect(code).toBe(1);
    expect(err.join('\n')).toContain('unexpected response shape');
  });
});