Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

11.8 KB
Raw Blame
import {
  chmodSync,
  existsSync,
  mkdtempSync,
  readFileSync,
  realpathSync,
  rmSync,
  writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { DEFAULT_MARKDOWNLINT_CONFIG } from '@inkeep/open-knowledge-core';
import { afterEach, beforeEach, describe, expect, test } from 'vitest';
import { parse as parseYaml } from 'yaml';
import { discoverMarkdownlintConfig, readOwnNativeRules } from './markdownlint-discovery.ts';
import { writeMarkdownlintRule } from './markdownlint-write.ts';

let dir: string;

beforeEach(() => {
  dir = realpathSync(mkdtempSync(join(tmpdir(), 'ok-mdl-write-')));
});
afterEach(() => {
  rmSync(dir, { recursive: true, force: true });
});

describe('writeMarkdownlintRule', () => {
  test('creates .markdownlint.json on first edit, seeded with the tuned defaults', () => {
    const res = writeMarkdownlintRule(dir, 'MD010', false);
    expect(res).toEqual({ action: 'written', file: '.markdownlint.json' });
    expect(existsSync(join(dir, '.markdownlint.json'))).toBe(true);
    expect(discoverMarkdownlintConfig(dir)?.rules).toEqual({
      ...DEFAULT_MARKDOWNLINT_CONFIG,
      MD010: false,
    });
  });

  test('merges a second rule, preserving the first', () => {
    writeMarkdownlintRule(dir, 'MD010', false);
    writeMarkdownlintRule(dir, 'MD013', true);
    expect(discoverMarkdownlintConfig(dir)?.rules).toEqual({
      ...DEFAULT_MARKDOWNLINT_CONFIG,
      MD010: false,
      MD013: true,
    });
  });

  test('updates an existing rule value in place', () => {
    writeMarkdownlintRule(dir, 'MD010', false);
    writeMarkdownlintRule(dir, 'MD010', true);
    expect(discoverMarkdownlintConfig(dir)?.rules).toEqual({
      ...DEFAULT_MARKDOWNLINT_CONFIG,
      MD010: true,
    });
  });

  test('writes a params object', () => {
    writeMarkdownlintRule(dir, 'MD007', { indent: 4 });
    expect(discoverMarkdownlintConfig(dir)?.rules).toEqual({
      ...DEFAULT_MARKDOWNLINT_CONFIG,
      MD007: { indent: 4 },
    });
  });

  test('does NOT seed a hand-authored file (edits merge into what the user wrote)', () => {
    writeFileSync(join(dir, '.markdownlint.json'), JSON.stringify({ MD013: false }), 'utf-8');
    writeMarkdownlintRule(dir, 'MD010', false);
    expect(discoverMarkdownlintConfig(dir)?.rules).toEqual({ MD013: false, MD010: false });
  });

  test('removing the last rule of a hand-authored file deletes it', () => {
    writeFileSync(join(dir, '.markdownlint.json'), JSON.stringify({ MD010: false }), 'utf-8');
    const res = writeMarkdownlintRule(dir, 'MD010', null);
    expect(res.action).toBe('deleted');
    expect(existsSync(join(dir, '.markdownlint.json'))).toBe(false);
  });

  test('removing one of several rules keeps the file', () => {
    writeFileSync(
      join(dir, '.markdownlint.json'),
      JSON.stringify({ MD010: false, MD013: false }),
      'utf-8',
    );
    writeMarkdownlintRule(dir, 'MD010', null);
    expect(discoverMarkdownlintConfig(dir)?.rules).toEqual({ MD013: false });
  });

  test('removing a rule when no file exists is a no-op (never creates a seeded file)', () => {
    const res = writeMarkdownlintRule(dir, 'MD010', null);
    expect(res.action).toBe('noop');
    expect(existsSync(join(dir, '.markdownlint.json'))).toBe(false);
  });

  test('preserves an existing .yaml file (writes YAML, not JSON)', () => {
    writeFileSync(join(dir, '.markdownlint.yaml'), 'MD013: false\n', 'utf-8');
    const res = writeMarkdownlintRule(dir, 'MD010', false);
    expect(res.file).toBe('.markdownlint.yaml');
    expect(existsSync(join(dir, '.markdownlint.json'))).toBe(false);
    const raw = readFileSync(join(dir, '.markdownlint.yaml'), 'utf-8');
    expect(parseYaml(raw)).toEqual({ MD013: false, MD010: false });
  });

  test('declines to rewrite an executable .cjs config (would corrupt the module)', () => {
    const original = 'module.exports = { MD013: false };';
    writeFileSync(join(dir, '.markdownlint.cjs'), original, 'utf-8');
    const res = writeMarkdownlintRule(dir, 'MD010', false);
    expect(res).toEqual({ action: 'declined-executable', file: '.markdownlint.cjs' });
    expect(readFileSync(join(dir, '.markdownlint.cjs'), 'utf-8')).toBe(original);
    expect(existsSync(join(dir, '.markdownlint.json'))).toBe(false);
  });

  test.runIf(process.getuid?.() !== 0)(
    'a transient read failure ABORTS the write — the hand-tuned file is untouched',
    () => {
      const original = JSON.stringify({ MD013: false, MD041: { level: 2 } });
      const file = join(dir, '.markdownlint.json');
      writeFileSync(file, original, 'utf-8');
      chmodSync(file, 0o000);
      try {
        expect(() => writeMarkdownlintRule(dir, 'MD010', false)).toThrow();
      } finally {
        chmodSync(file, 0o644);
      }
      expect(readFileSync(file, 'utf-8')).toBe(original);
    },
  );

  test('a MALFORMED file is still clobbered cleanly (documented behavior)', () => {
    writeFileSync(join(dir, '.markdownlint.json'), '{ not valid json', 'utf-8');
    const res = writeMarkdownlintRule(dir, 'MD010', false);
    expect(res.action).toBe('written');
    expect(discoverMarkdownlintConfig(dir)?.rules).toEqual({ MD010: false });
  });

  test('preserves an extends reference verbatim — never materializes the base', () => {
    writeFileSync(join(dir, 'base.markdownlint.json'), JSON.stringify({ MD041: false }), 'utf-8');
    writeFileSync(
      join(dir, '.markdownlint.json'),
      JSON.stringify({ extends: './base.markdownlint.json', MD013: false }),
      'utf-8',
    );
    writeMarkdownlintRule(dir, 'MD010', false);
    expect(readOwnNativeRules(dir)?.rules).toEqual({
      extends: './base.markdownlint.json',
      MD013: false,
      MD010: false,
    });
    expect(discoverMarkdownlintConfig(dir)?.rules).toEqual({
      MD041: false,
      MD013: false,
      MD010: false,
    });
  });
});

describe('JSONC comment preservation', () => {
  const COMMENTED = [
    '{',
    '  // tuned for prose, not code',
    '  "MD013": false, /* long lines OK */',
    '  "MD041": false',
    '}',
    '',
  ].join('\n');

  test('toggling an existing rule keeps every comment, changing only the value', () => {
    writeFileSync(join(dir, '.markdownlint.jsonc'), COMMENTED, 'utf-8');
    const res = writeMarkdownlintRule(dir, 'MD013', true);
    expect(res).toEqual({ action: 'written', file: '.markdownlint.jsonc' });
    const raw = readFileSync(join(dir, '.markdownlint.jsonc'), 'utf-8');
    expect(raw).toContain('// tuned for prose, not code');
    expect(raw).toContain('/* long lines OK */');
    expect(discoverMarkdownlintConfig(dir)?.rules).toEqual({ MD013: true, MD041: false });
  });

  test('adding a new rule appends it without disturbing comments', () => {
    writeFileSync(join(dir, '.markdownlint.jsonc'), COMMENTED, 'utf-8');
    writeMarkdownlintRule(dir, 'MD007', { indent: 4 });
    const raw = readFileSync(join(dir, '.markdownlint.jsonc'), 'utf-8');
    expect(raw).toContain('// tuned for prose, not code');
    expect(discoverMarkdownlintConfig(dir)?.rules).toEqual({
      MD013: false,
      MD041: false,
      MD007: { indent: 4 },
    });
  });

  test('removing a rule keeps the remaining config and its comments', () => {
    writeFileSync(join(dir, '.markdownlint.jsonc'), COMMENTED, 'utf-8');
    writeMarkdownlintRule(dir, 'MD041', null);
    const raw = readFileSync(join(dir, '.markdownlint.jsonc'), 'utf-8');
    expect(raw).toContain('// tuned for prose, not code');
    expect(discoverMarkdownlintConfig(dir)?.rules).toEqual({ MD013: false });
  });

  test('removing the LAST rule keeps a file that still carries comments', () => {
    writeFileSync(
      join(dir, '.markdownlint.jsonc'),
      '// our lint philosophy, hand-tuned\n{\n  "MD013": false\n}\n',
      'utf-8',
    );
    const res = writeMarkdownlintRule(dir, 'MD013', null);
    expect(res.action).toBe('written');
    const raw = readFileSync(join(dir, '.markdownlint.jsonc'), 'utf-8');
    expect(raw).toContain('// our lint philosophy, hand-tuned');
    expect(discoverMarkdownlintConfig(dir)?.rules).toEqual({});
  });

  test('a comment annotating ONLY the removed rule goes with it; an emptied file is deleted', () => {
    writeFileSync(
      join(dir, '.markdownlint.jsonc'),
      '{\n  // about MD013 specifically\n  "MD013": false\n}\n',
      'utf-8',
    );
    const res = writeMarkdownlintRule(dir, 'MD013', null);
    expect(res.action).toBe('deleted');
    expect(existsSync(join(dir, '.markdownlint.jsonc'))).toBe(false);
  });

  test('removing the last rule of a comment-free .jsonc still deletes the file', () => {
    writeFileSync(join(dir, '.markdownlint.jsonc'), '{ "MD013": false }\n', 'utf-8');
    const res = writeMarkdownlintRule(dir, 'MD013', null);
    expect(res.action).toBe('deleted');
    expect(existsSync(join(dir, '.markdownlint.jsonc'))).toBe(false);
  });
});

describe('JSONC format-preserving round-trip', () => {
  const HAND_AUTHORED = [
    '// hand-tuned markdownlint rules',
    '{',
    '  "extends": "./shared.markdownlint.json",',
    '  "MD007": { "indent": 4 },',
    '  "MD013": false,',
    '}',
    '',
  ].join('\n');

  test('writing one rule keeps the comment, extends, trailing comma, and default:false intact', () => {
    writeFileSync(join(dir, '.markdownlint.jsonc'), HAND_AUTHORED, 'utf-8');

    const res = writeMarkdownlintRule(dir, 'MD007', { indent: 2 });
    expect(res).toEqual({ action: 'written', file: '.markdownlint.jsonc' });

    const raw = readFileSync(join(dir, '.markdownlint.jsonc'), 'utf-8');
    expect(raw).toContain('// hand-tuned markdownlint rules');
    expect(raw).toContain('"extends": "./shared.markdownlint.json"');
    expect(raw).toContain('"MD013": false');
    expect(raw).toMatch(/,\s*}\s*$/);

    expect(readOwnNativeRules(dir)?.rules).toEqual({
      extends: './shared.markdownlint.json',
      MD007: { indent: 2 },
      MD013: false,
    });
  });
});

describe('alias-keyed configs', () => {
  test('setting a rule writes through the existing alias key — no dual MD### key', () => {
    writeFileSync(
      join(dir, '.markdownlint.jsonc'),
      '{\n  // prefer readable names\n  "line-length": { "line_length": 100 }\n}\n',
      'utf-8',
    );
    writeMarkdownlintRule(dir, 'MD013', false);
    const raw = readFileSync(join(dir, '.markdownlint.jsonc'), 'utf-8');
    expect(raw).toContain('"line-length": false');
    expect(raw).not.toContain('MD013');
    expect(raw).toContain('// prefer readable names');
  });

  test('with mixed keys, the governing (last) key is edited; the shadowed one is left alone', () => {
    writeFileSync(
      join(dir, '.markdownlint.json'),
      '{\n  "MD013": false,\n  "line-length": true\n}\n',
      'utf-8',
    );
    writeMarkdownlintRule(dir, 'MD013', { line_length: 120 });
    const parsed = JSON.parse(readFileSync(join(dir, '.markdownlint.json'), 'utf-8'));
    expect(parsed).toEqual({ MD013: false, 'line-length': { line_length: 120 } });
  });

  test('removing a rule deletes EVERY key addressing it (a shadowed alias would resurrect it)', () => {
    writeFileSync(
      join(dir, '.markdownlint.json'),
      JSON.stringify({ MD013: false, 'line-length': true, MD010: false }),
      'utf-8',
    );
    writeMarkdownlintRule(dir, 'MD013', null);
    expect(readOwnNativeRules(dir)?.rules).toEqual({ MD010: false });
  });

  test('setting through an alias works on YAML too', () => {
    writeFileSync(join(dir, '.markdownlint.yaml'), 'line-length: false\n', 'utf-8');
    writeMarkdownlintRule(dir, 'MD013', true);
    const raw = readFileSync(join(dir, '.markdownlint.yaml'), 'utf-8');
    expect(parseYaml(raw)).toEqual({ 'line-length': true });
  });

  test('a rule id outside the catalog falls back to exact-key semantics', () => {
    writeFileSync(join(dir, '.markdownlint.json'), JSON.stringify({ MD999: true }), 'utf-8');
    writeMarkdownlintRule(dir, 'MD999', false);
    expect(readOwnNativeRules(dir)?.rules).toEqual({ MD999: false });
  });
});