Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

12.0 KB
Raw Blame
import {
  DEFAULT_LINTER_CONFIG,
  type LinterConfig,
  lintDocument,
} from '@inkeep/open-knowledge-core';
import { describe, expect, test } from 'vitest';
import { computeBrokenOutboundLinks } from '../backlink-index.ts';
import { buildIndexMarkdown, type IndexEntry } from './generate-index.ts';

const OKF_LINT_CONFIG: LinterConfig = {
  ...DEFAULT_LINTER_CONFIG,
  enabled: true,
  plugins: { ...DEFAULT_LINTER_CONFIG.plugins, okf: { enabled: true } },
};

const ENTRIES: IndexEntry[] = [
  {
    path: 'welcome.md',
    title: 'Welcome',
    description: 'what this knowledge base is and how it is organized',
    type: 'note',
  },
  {
    path: 'concepts/bounded-context.md',
    title: 'Bounded Context',
    description: 'where a model stops applying',
    type: 'concept',
  },
  {
    path: 'concepts/ubiquitous-language.md',
    title: 'Ubiquitous Language',
    description: undefined,
    type: 'concept',
  },
  { path: 'scratch.md', title: 'Scratch', description: undefined, type: undefined },
];

const ADMITTED = ['index', ...ENTRIES.map((e) => e.path.replace(/\.md$/, ''))];

describe('generated index — OKF conformance', () => {
  test('the generated root index produces zero okf findings', async () => {
    const markdown = buildIndexMarkdown(ENTRIES, { warningScope: false, isRoot: true });

    const findings = await lintDocument(markdown, OKF_LINT_CONFIG, 'index.md');
    const detail = findings
      .map((f) => `${f.code} @ ${f.range.start.line + 1} — ${f.message}`)
      .join('; ');

    expect(findings, `generated root index produced okf findings: ${detail}`).toEqual([]);
  });

  test('a generated non-root index produces zero okf findings', async () => {
    const markdown = buildIndexMarkdown(ENTRIES, { warningScope: false, isRoot: false });
    const findings = await lintDocument(markdown, OKF_LINT_CONFIG, 'concepts/index.md');

    expect(findings.map((f) => f.code)).toEqual([]);
  });

  test('an empty bundle still yields a conformant root index', async () => {
    const markdown = buildIndexMarkdown([], { warningScope: false, isRoot: true });
    const findings = await lintDocument(markdown, OKF_LINT_CONFIG, 'index.md');
    expect(findings.map((f) => f.code)).toEqual([]);
  });

  test('every link in the generated index resolves', () => {
    const markdown = buildIndexMarkdown(ENTRIES, { warningScope: false, isRoot: true });
    const broken = computeBrokenOutboundLinks(markdown, 'index', ADMITTED);

    expect(
      broken,
      `generated index emitted unresolvable links: ${broken.map((b) => b.href).join(', ')}`,
    ).toEqual([]);
  });

  test('a bare folder href would be caught — the guard is not vacuous', () => {
    const withFolderLink = ['# concept', '', '* [concepts/](./concepts/) - a folder', ''].join(
      '\n',
    );
    const broken = computeBrokenOutboundLinks(withFolderLink, 'index', ADMITTED);

    expect(broken.map((b) => b.href)).toEqual(['./concepts/']);
  });
});

const DEFAULT_PROFILE_LINT_CONFIG: LinterConfig = {
  ...DEFAULT_LINTER_CONFIG,
  enabled: true,
  plugins: {
    ...DEFAULT_LINTER_CONFIG.plugins,
    markdownlint: { ...DEFAULT_LINTER_CONFIG.plugins.markdownlint, enabled: true },
    okf: { enabled: true },
  },
};

async function findingCodes(markdown: string, docName: string): Promise<string[]> {
  const findings = await lintDocument(markdown, DEFAULT_PROFILE_LINT_CONFIG, docName);
  return findings.map((f) => `${f.code} @ ${f.range.start.line + 1} — ${f.message}`);
}

describe('generated index — default lint profile', () => {
  test('the generated root index is clean under markdownlint defaults', async () => {
    expect(
      await findingCodes(
        buildIndexMarkdown(ENTRIES, { warningScope: false, isRoot: true }),
        'index.md',
      ),
    ).toEqual([]);
  });

  test('a generated non-root index is clean under markdownlint defaults', async () => {
    expect(
      await findingCodes(
        buildIndexMarkdown(ENTRIES, { warningScope: false, isRoot: false }),
        'concepts/index.md',
      ),
    ).toEqual([]);
  });

  test('an empty bundle is clean under markdownlint defaults', async () => {
    expect(
      await findingCodes(buildIndexMarkdown([], { warningScope: false, isRoot: true }), 'index.md'),
    ).toEqual([]);
  });

  test('a Subdirectories document type plus a child directory is clean under markdownlint defaults', async () => {
    const markdown = buildIndexMarkdown(
      [
        {
          path: 'concepts/directory-notes.md',
          title: 'Directory notes',
          type: 'Subdirectories',
        },
      ],
      {
        warningScope: false,
        isRoot: false,
        directory: 'concepts',
        subdirectories: [{ directory: 'concepts/nested', title: 'nested' }],
      },
    );

    expect(await findingCodes(markdown, 'concepts/index.md')).toEqual([]);
  });

  test('an Index document type is clean under markdownlint defaults', async () => {
    const readmeOnly = buildIndexMarkdown(
      [{ path: 'testing/README.md', title: 'Testing', type: 'Index' }],
      { warningScope: false, isRoot: false, directory: 'testing' },
    );

    expect(await findingCodes(readmeOnly, 'testing/index.md')).toEqual([]);
  });

  test('an Index document type alongside other typed sections is clean under markdownlint defaults', async () => {
    const multiSection = buildIndexMarkdown(
      [
        { path: 'auth/README.md', title: 'Auth', type: 'Index' },
        { path: 'auth/login-flow.md', title: 'Login flow', type: 'Flow' },
        { path: 'auth/sso.md', title: 'SSO', type: 'Feature Doc' },
      ],
      { warningScope: false, isRoot: false, directory: 'auth' },
    );

    expect(await findingCodes(multiSection, 'auth/index.md')).toEqual([]);
  });

  test('a root index with an Index document type is clean under markdownlint defaults', async () => {
    const markdown = buildIndexMarkdown(
      [
        { path: 'README.md', title: 'Knowledge base', type: 'Index' },
        { path: 'welcome.md', title: 'Welcome', type: 'note' },
      ],
      { warningScope: false, isRoot: true },
    );

    expect(await findingCodes(markdown, 'index.md')).toEqual([]);
  });

  test('a duplicate heading would be caught — the guard is not vacuous', async () => {
    const duplicateHeading = ['# Index', '', '## Index', '', '* [Testing](./README.md)', ''];

    expect(await findingCodes(duplicateHeading.join('\n'), 'testing/index.md')).toEqual([
      expect.stringContaining('MD024'),
    ]);
  });

  test('level-one sections would be caught — the guard is not vacuous', async () => {
    const levelOneSections = [
      '---',
      'okf_version: "0.2"',
      '---',
      '',
      '# concept',
      '',
      '* [Bounded Context](./concepts/bounded-context.md) - where a model stops applying',
      '',
      '# note',
      '',
      '* [Welcome](./welcome.md) - what this knowledge base is',
      '',
    ].join('\n');

    expect(await findingCodes(levelOneSections, 'index.md')).toEqual([
      expect.stringContaining('MD025'),
    ]);
  });

  test('demoting sections without a title would be caught too', async () => {
    const noTitle = ['## concept', '', '* [Bounded Context](./concepts/bounded-context.md)', ''];

    expect(await findingCodes(noTitle.join('\n'), 'concepts/index.md')).toEqual([
      expect.stringContaining('MD041'),
    ]);
  });
});

describe('generated index — heading-identity agreement with MD024', () => {
  const mdOnly = (codes: string[]): string[] => codes.filter((code) => code.includes('MD024'));

  const withType = (type: string): string =>
    buildIndexMarkdown(
      [
        { path: 'readme.md', title: 'Overview', description: undefined, type },
        { path: 'flow.md', title: 'Login flow', description: undefined, type: 'Flow' },
      ],
      { warningScope: false, isRoot: false, directory: '' },
    );

  test('the exact Index type merges into the title', async () => {
    const markdown = withType('Index');

    expect(mdOnly(await findingCodes(markdown, 'index.md')), `emitted:\n${markdown}`).toEqual([]);
    expect(markdown, `emitted:\n${markdown}`).toContain('](./readme.md)');
    expect(markdown).not.toContain('## Index');
  });

  test.each([
    ['Index #', 'Index \\#'],
    ['Index   ##', 'Index \\#\\#'],
    ['<b></b>Index', '\\<b\\>\\<\\/b\\>Index'],
    ['Index<!--x-->', 'Index\\<\\!\\-\\-x\\-\\-\\>'],
    ['Index<!-- a>b -->', 'Index\\<\\!\\-\\- a\\>b \\-\\-\\>'],
    ['Index<a href="x>y">', 'Index\\<a href\\=\\"x\\>y\\"\\>'],
    ['index', 'index'],
    ['INDEX', 'INDEX'],
    ['Indexes', 'Indexes'],
    ['Index Notes', 'Index Notes'],
    ['Flow', 'Flow'],
    ['Index <b>#</b>', 'Index \\<b\\>\\#\\<\\/b\\>'],
    ['Index<b> #</b>', 'Index\\<b\\> \\#\\<\\/b\\>'],
  ])(
    'a literal type distinct from the title keeps its own section: %j',
    async (type, emittedHeading) => {
      const markdown = withType(type);

      expect(markdown, `emitted:\n${markdown}`).toContain(`## ${emittedHeading}`);
      expect(mdOnly(await findingCodes(markdown, 'index.md')), `emitted:\n${markdown}`).toEqual([]);
    },
  );

  test.each([
    [
      ['#', '##'],
      ['\\#', '\\#\\#'],
    ],
    [
      ['#', '<b></b>'],
      ['\\#', '\\<b\\>\\<\\/b\\>'],
    ],
    [
      ['<b></b>', '<i></i>'],
      ['\\<b\\>\\<\\/b\\>', '\\<i\\>\\<\\/i\\>'],
    ],
  ])(
    'punctuation and HTML-shaped literal types remain distinct: %j',
    async (pair, emittedHeadings) => {
      const markdown = buildIndexMarkdown(
        [
          { path: 'a.md', title: 'A', description: undefined, type: pair[0] },
          { path: 'b.md', title: 'B', description: undefined, type: pair[1] },
        ],
        { warningScope: false, isRoot: false, directory: '' },
      );

      expect(mdOnly(await findingCodes(markdown, 'index.md')), `emitted:\n${markdown}`).toEqual([]);
      expect(markdown).toContain('](./a.md)');
      expect(markdown).toContain('](./b.md)');

      const sections = (markdown.match(/^## .+$/gm) ?? []).map((line) => line.slice(3));
      expect(sections, `emitted:\n${markdown}`).toEqual(emittedHeadings);
    },
  );

  test('two literal sections remain distinct when Markdown would reduce them to one heading', async () => {
    const markdown = buildIndexMarkdown(
      [
        { path: 'a.md', title: 'A', description: undefined, type: 'Flow' },
        { path: 'b.md', title: 'B', description: undefined, type: 'Flow #' },
      ],
      { warningScope: false, isRoot: false, directory: '' },
    );

    expect(mdOnly(await findingCodes(markdown, 'index.md')), `emitted:\n${markdown}`).toEqual([]);
    expect(markdown).toContain('## Flow\n');
    expect(markdown).toContain('## Flow \\#\n');
    expect(markdown).toContain('](./a.md)');
    expect(markdown).toContain('](./b.md)');
  });

  test('two empty headings would be caught — the guard is not vacuous', async () => {
    const handBuilt = [
      '# Index',
      '',
      '* [Overview](./readme.md)',
      '',
      '## #',
      '',
      '* [A](./a.md)',
      '',
      '## <b></b>',
      '',
      '* [B](./b.md)',
      '',
    ].join('\n');

    expect(mdOnly(await findingCodes(handBuilt, 'index.md')), `emitted:\n${handBuilt}`).toEqual([
      expect.stringContaining('MD024'),
    ]);
  });

  test('a duplicate reached through inline HTML would be caught — the guard is not vacuous', async () => {
    const handBuilt = [
      '# Index',
      '',
      '* [Overview](./readme.md)',
      '',
      '## <b></b>Index',
      '',
      '* [Other](./other.md)',
      '',
    ].join('\n');

    const codes = await findingCodes(handBuilt, 'index.md');

    expect(mdOnly(codes), `emitted:\n${handBuilt}`).toEqual([expect.stringContaining('MD024')]);
    expect(codes.some((code) => code.includes('MD033'))).toBe(true);
  });

  test('a duplicate reached through an ATX closer would be caught — the guard is not vacuous', async () => {
    const handBuilt = [
      '# Index',
      '',
      '* [Overview](./readme.md)',
      '',
      '## Index #',
      '',
      '* [Other](./other.md)',
      '',
    ].join('\n');

    expect(mdOnly(await findingCodes(handBuilt, 'index.md'))).toEqual([
      expect.stringContaining('MD024'),
    ]);
  });
});