Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

14.0 KB
Raw Blame
import {
  chmodSync,
  mkdirSync,
  mkdtempSync,
  realpathSync,
  rmSync,
  symlinkSync,
  writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import {
  CANONICAL_SCHEMA_DIALECT_URIS,
  DEFAULT_LINTER_CONFIG,
  DEFAULT_SCHEMA_DIALECT,
  type LinterConfig,
  SUPPORTED_SCHEMA_DIALECTS,
} from '@inkeep/open-knowledge-core';
import { afterEach, beforeEach, describe, expect, test } from 'vitest';
import { runningAsRoot } from '../../../../test-support/capabilities.test-helper.ts';
import {
  listProjectSchemaFiles,
  resolveFrontmatterSchemas,
  unmatchedAppliesToProblems,
} from './frontmatter-schemas.ts';
import { composeFrontmatterSchemasConfig, resolveEffectiveLinterConfig } from './resolve-config.ts';

let projectDir: string;
let outsideDir: string;

beforeEach(() => {
  projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-fm-schemas-')));
  outsideDir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-fm-outside-')));
});

afterEach(() => {
  rmSync(projectDir, { recursive: true, force: true });
  rmSync(outsideDir, { recursive: true, force: true });
});

function write(rel: string, content: string): string {
  const abs = join(projectDir, rel);
  mkdirSync(dirname(abs), { recursive: true });
  writeFileSync(abs, content);
  return abs;
}

const GOOD_SCHEMA = JSON.stringify({
  $schema: 'http://json-schema.org/draft-07/schema#',
  type: 'object',
  required: ['title'],
});

describe('resolveFrontmatterSchemas — loading', () => {
  test('loads a good schema with content + canonical key', () => {
    const abs = write('.ok/schemas/doc.schema.json', GOOD_SCHEMA);
    const { entries, problems } = resolveFrontmatterSchemas(projectDir, [
      { appliesTo: 'docs/**', file: '.ok/schemas/doc.schema.json' },
    ]);
    expect(problems).toEqual([]);
    expect(entries).toHaveLength(1);
    expect(entries[0]?.schema).toMatchObject({ required: ['title'] });
    expect(entries[0]?.key).toBe(realpathSync(abs));
    expect(entries[0]?.appliesTo).toBe('docs/**');
  });

  test('schemas can live anywhere in the project, not only .ok/schemas/', () => {
    write('schemas/custom.json', GOOD_SCHEMA);
    const { entries, problems } = resolveFrontmatterSchemas(projectDir, [
      { file: 'schemas/custom.json' },
    ]);
    expect(problems).toEqual([]);
    expect(entries[0]?.schema).toBeDefined();
  });

  test('a broken file mapped disabled-then-enabled still reports once', () => {
    write('.ok/schemas/broken.json', '{ not json');
    const { problems } = resolveFrontmatterSchemas(projectDir, [
      { file: '.ok/schemas/broken.json', appliesTo: 'archive/**', enabled: false },
      { file: '.ok/schemas/broken.json', appliesTo: 'docs/**', enabled: true },
    ]);
    expect(problems).toHaveLength(1);
    expect(problems[0]).toContain('.ok/schemas/broken.json');
  });

  test('a broken file mapped by two enabled mappings is not double-reported', () => {
    write('.ok/schemas/broken.json', '{ not json');
    const { problems } = resolveFrontmatterSchemas(projectDir, [
      { file: '.ok/schemas/broken.json', appliesTo: 'docs/**' },
      { file: '.ok/schemas/broken.json', appliesTo: 'specs/**' },
    ]);
    expect(problems).toHaveLength(1);
  });

  test('a broken file mapped only by a disabled mapping stays silent', () => {
    write('.ok/schemas/broken.json', '{ not json');
    const { problems } = resolveFrontmatterSchemas(projectDir, [
      { file: '.ok/schemas/broken.json', appliesTo: 'archive/**', enabled: false },
    ]);
    expect(problems).toEqual([]);
  });

  test('a missing file is a schemaError problem; the entry stays content-less with a key', () => {
    const { entries, problems } = resolveFrontmatterSchemas(projectDir, [
      { file: '.ok/schemas/nope.json' },
    ]);
    expect(problems).toHaveLength(1);
    expect(problems[0]).toContain('.ok/schemas/nope.json');
    expect(problems[0]).toContain('cannot read');
    expect(entries[0]?.schema).toBeUndefined();
    expect(entries[0]?.key).toBe('.ok/schemas/nope.json');
  });

  test('malformed JSON is a problem, never a throw', () => {
    write('bad.json', '{ not json');
    const { entries, problems } = resolveFrontmatterSchemas(projectDir, [{ file: 'bad.json' }]);
    expect(problems[0]).toContain('malformed JSON');
    expect(entries[0]?.schema).toBeUndefined();
  });

  test('non-object JSON is a problem', () => {
    write('array.json', '["not", "an", "object"]');
    const { problems } = resolveFrontmatterSchemas(projectDir, [{ file: 'array.json' }]);
    expect(problems[0]).toContain('not a JSON object');
  });

  test.each(SUPPORTED_SCHEMA_DIALECTS)('a %s schema loads cleanly', (dialect) => {
    write(
      'dialect.json',
      JSON.stringify({
        $schema: CANONICAL_SCHEMA_DIALECT_URIS[dialect],
        type: 'object',
        required: ['title'],
      }),
    );
    const { entries, problems } = resolveFrontmatterSchemas(projectDir, [{ file: 'dialect.json' }]);
    expect(problems).toEqual([]);
    expect(entries[0]?.schema).toMatchObject({ required: ['title'] });
  });

  test('a schema with no $schema loads (absent means the default dialect)', () => {
    write('bare.json', JSON.stringify({ type: 'object', required: ['title'] }));
    const { entries, problems } = resolveFrontmatterSchemas(projectDir, [{ file: 'bare.json' }]);
    expect(problems).toEqual([]);
    expect(entries[0]?.schema).toMatchObject({ required: ['title'] });
  });

  test('an unsupported dialect is skipped with a problem naming what is supported', () => {
    write(
      'draft04.json',
      JSON.stringify({ $schema: 'http://json-schema.org/draft-04/schema#', type: 'object' }),
    );
    const { entries, problems } = resolveFrontmatterSchemas(projectDir, [{ file: 'draft04.json' }]);
    expect(problems[0]).toContain('unsupported dialect');
    expect(problems[0]).toContain('draft-04');
    for (const dialect of SUPPORTED_SCHEMA_DIALECTS) {
      expect(problems[0]).toContain(dialect);
    }
    expect(problems[0]).toContain(CANONICAL_SCHEMA_DIALECT_URIS[DEFAULT_SCHEMA_DIALECT]);
    expect(entries[0]?.schema).toBeUndefined();
  });

  test('a schema ajv refuses is a problem', () => {
    write('refused.json', JSON.stringify({ type: 'object', properties: { x: { pattern: '[' } } }));
    const { problems } = resolveFrontmatterSchemas(projectDir, [{ file: 'refused.json' }]);
    expect(problems[0]).toContain('does not compile');
  });

  test('an invalid appliesTo glob surfaces as a problem while the schema still loads', () => {
    write('ok.json', GOOD_SCHEMA);
    const { entries, problems } = resolveFrontmatterSchemas(projectDir, [
      { appliesTo: ['docs/**', 'docs/['], file: 'ok.json' },
    ]);
    expect(problems).toHaveLength(1);
    expect(problems[0]).toContain('invalid appliesTo glob');
    expect(problems[0]).toContain('docs/[');
    expect(entries[0]?.schema).toBeDefined();
  });

  test('a suspicious glob surfaces an advisory problem; disabled mappings stay silent', () => {
    write('ok.json', GOOD_SCHEMA);
    const { problems } = resolveFrontmatterSchemas(projectDir, [
      { appliesTo: ['docs/', 'notes/**/*.md'], file: 'ok.json' },
    ]);
    expect(problems).toHaveLength(2);
    expect(problems[0]).toContain('suspicious appliesTo glob');
    expect(problems[0]).toContain('trailing slash');
    expect(problems[1]).toContain('extension');

    const silent = resolveFrontmatterSchemas(projectDir, [
      { appliesTo: ['docs/'], file: 'ok.json', enabled: false },
    ]);
    expect(silent.problems).toEqual([]);
  });
});

describe('resolveFrontmatterSchemas — escape guards', () => {
  test('a .. path is refused lexically, even when the target exists', () => {
    writeFileSync(join(outsideDir, 'evil.json'), GOOD_SCHEMA);
    const rel = `../${outsideDir.split('/').pop()}/evil.json`;
    const { entries, problems } = resolveFrontmatterSchemas(projectDir, [{ file: rel }]);
    expect(problems[0]).toContain('outside the project');
    expect(entries[0]?.schema).toBeUndefined();
  });

  test('a symlink pointing outside the project is refused', () => {
    writeFileSync(join(outsideDir, 'evil.json'), GOOD_SCHEMA);
    symlinkSync(join(outsideDir, 'evil.json'), join(projectDir, 'link.json'));
    const { entries, problems } = resolveFrontmatterSchemas(projectDir, [{ file: 'link.json' }]);
    expect(problems[0]).toContain('outside the project');
    expect(entries[0]?.schema).toBeUndefined();
  });

  test('a symlink resolving inside the project is fine (realpath identity)', () => {
    write('real/doc.schema.json', GOOD_SCHEMA);
    symlinkSync(join(projectDir, 'real/doc.schema.json'), join(projectDir, 'alias.json'));
    const { entries, problems } = resolveFrontmatterSchemas(projectDir, [{ file: 'alias.json' }]);
    expect(problems).toEqual([]);
    expect(entries[0]?.key).toBe(realpathSync(join(projectDir, 'real/doc.schema.json')));
  });

  test('an unreadable file is a cannot-read problem', (ctx) => {
    ctx.skip(runningAsRoot, 'root bypasses the chmod refusal this test induces');
    const abs = write('locked.json', GOOD_SCHEMA);
    chmodSync(abs, 0o000);
    const { problems } = resolveFrontmatterSchemas(projectDir, [{ file: 'locked.json' }]);
    expect(problems[0]).toContain('cannot read');
    chmodSync(abs, 0o644);
  });
});

describe('resolveFrontmatterSchemas — dedup identity', () => {
  test('./-spelled duplicates of one file share a canonical key and read once', () => {
    const abs = write('.ok/schemas/doc.schema.json', GOOD_SCHEMA);
    const { entries, problems } = resolveFrontmatterSchemas(projectDir, [
      { appliesTo: 'docs/**', file: '.ok/schemas/doc.schema.json' },
      { appliesTo: 'specs/**', file: './.ok/schemas/doc.schema.json' },
    ]);
    expect(problems).toEqual([]);
    expect(entries[0]?.key).toBe(realpathSync(abs));
    expect(entries[1]?.key).toBe(realpathSync(abs));
  });

  test('distinct files with identical content keep distinct keys', () => {
    write('a.json', GOOD_SCHEMA);
    write('b.json', GOOD_SCHEMA);
    const { entries } = resolveFrontmatterSchemas(projectDir, [
      { file: 'a.json' },
      { file: 'b.json' },
    ]);
    expect(entries[0]?.key).not.toBe(entries[1]?.key);
  });
});

describe('composeFrontmatterSchemasConfig + resolveEffectiveLinterConfig', () => {
  function baseWith(schemas: { appliesTo?: string | string[]; file: string }[]): LinterConfig {
    return {
      ...DEFAULT_LINTER_CONFIG,
      plugins: {
        ...DEFAULT_LINTER_CONFIG.plugins,
        frontmatter: { enabled: true, schemas },
      },
    };
  }

  test('injects loaded content into the effective slice', () => {
    write('.ok/schemas/doc.schema.json', GOOD_SCHEMA);
    const problems: string[] = [];
    const effective = composeFrontmatterSchemasConfig(
      projectDir,
      baseWith([{ appliesTo: 'docs/**', file: '.ok/schemas/doc.schema.json' }]),
      (p) => problems.push(p),
    );
    expect(problems).toEqual([]);
    expect(effective.plugins.frontmatter.schemas[0]?.schema).toBeDefined();
  });

  test('disabled slice or zero mappings skip the disk entirely', () => {
    const disabled = composeFrontmatterSchemasConfig(projectDir, DEFAULT_LINTER_CONFIG);
    expect(disabled).toBe(DEFAULT_LINTER_CONFIG);
    const empty = composeFrontmatterSchemasConfig(projectDir, baseWith([]));
    expect(empty.plugins.frontmatter.schemas).toEqual([]);
  });

  test('already-resolved entries pass through without re-reading (audit precompose)', () => {
    write('.ok/schemas/doc.schema.json', GOOD_SCHEMA);
    const once = composeFrontmatterSchemasConfig(
      projectDir,
      baseWith([{ file: '.ok/schemas/doc.schema.json' }]),
    );
    rmSync(join(projectDir, '.ok/schemas/doc.schema.json'));
    const twice = composeFrontmatterSchemasConfig(projectDir, once);
    expect(twice).toBe(once);
  });

  test('projectDir resolution holds when contentDir is a subfolder (content.dir)', () => {
    write('.ok/schemas/doc.schema.json', GOOD_SCHEMA);
    const contentDir = join(projectDir, 'kb');
    mkdirSync(contentDir, { recursive: true });
    const problems: string[] = [];
    const effective = resolveEffectiveLinterConfig(
      contentDir,
      baseWith([{ file: '.ok/schemas/doc.schema.json' }]),
      { projectDir, onProblem: (p) => problems.push(p) },
    );
    expect(problems).toEqual([]);
    expect(effective.plugins.frontmatter.schemas[0]?.schema).toBeDefined();
  });
});

describe('listProjectSchemaFiles', () => {
  test('enumerates .ok/schemas/*.json as project-relative paths, sorted', () => {
    write('.ok/schemas/zebra.json', '{}');
    write('.ok/schemas/alpha.schema.json', '{}');
    write('.ok/schemas/notes.JSON', '{}');
    write('.ok/schemas/readme.md', '# not a schema');
    mkdirSync(join(projectDir, '.ok/schemas/nested'), { recursive: true });
    const { schemas, truncated } = listProjectSchemaFiles(projectDir);
    expect(schemas).toEqual([
      '.ok/schemas/alpha.schema.json',
      '.ok/schemas/notes.JSON',
      '.ok/schemas/zebra.json',
    ]);
    expect(truncated).toBe(false);
  });

  test('missing .ok/schemas/ is an empty list, not an error', () => {
    expect(listProjectSchemaFiles(projectDir)).toEqual({ schemas: [], truncated: false });
  });
});

describe('unmatchedAppliesToProblems', () => {
  const docs = ['docs/guide.md', 'notes/todo.md'];

  test('reports enabled mappings whose authored globs match zero docs', () => {
    const problems = unmatchedAppliesToProblems(
      [{ file: '.ok/schemas/doc.schema.json', enabled: true, appliesTo: ['docs/**', 'specs/**'] }],
      docs,
    );
    expect(problems).toEqual([
      'unmatched appliesTo glob "specs/**" — matches no docs in this project (frontmatter mapping for .ok/schemas/doc.schema.json)',
    ]);
  });

  test('disabled mappings stay silent', () => {
    const problems = unmatchedAppliesToProblems(
      [{ file: '.ok/schemas/doc.schema.json', enabled: false, appliesTo: ['specs/**'] }],
      docs,
    );
    expect(problems).toEqual([]);
  });

  test('mappings without appliesTo (implicit every doc) report nothing', () => {
    const problems = unmatchedAppliesToProblems(
      [{ file: '.ok/schemas/doc.schema.json', enabled: true }],
      docs,
    );
    expect(problems).toEqual([]);
  });
});