Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

8.5 KB
Raw Blame
import { spawnSync } from 'node:child_process';
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { pathToFileURL } from 'node:url';
import { beforeAll, describe, expect, test } from 'vitest';

const REPO_ROOT = join(__dirname, '..', '..', '..', '..');
const OXLINT_BIN = join(REPO_ROOT, 'node_modules', '.bin', 'oxlint');
const FIXTURE_DIR = 'lint-plugins/no-comments/__fixtures__';
const ALL_SCOPE_CONFIG = `${FIXTURE_DIR}/oxlint.fixture.json`;
const DECLARED_SCOPE_CONFIG = `${FIXTURE_DIR}/oxlint.declared-scope.fixture.json`;
const PLUGIN_REL = './lint-plugins/no-comments/plugin.mjs';
const RULE_ID = 'no-comments/no-comments';

type Diagnostic = { line: number; column: number; class: string; message: string };
type Run = { status: number | null; raw: string; diagnostics: Diagnostic[] };
type RunOxlint = (input: { bin: string; cwd: string; config: string; target: string }) => Run;

let runOxlintHelper: RunOxlint;

async function loadRunOxlint(): Promise<RunOxlint> {
  const moduleUrl = pathToFileURL(
    join(REPO_ROOT, 'lint-plugins/no-comments/run-oxlint.test-helper.mjs'),
  ).href;
  const loaded = (await import(/* @vite-ignore */ moduleUrl)) as { runOxlint: RunOxlint };
  return loaded.runOxlint;
}

function runOxlint(config: string, fixture: string): Run {
  return runOxlintHelper({
    bin: OXLINT_BIN,
    cwd: REPO_ROOT,
    config,
    target: `${FIXTURE_DIR}/${fixture}`,
  });
}

type Violation = { class: string; comment: { line: number; column: number } };
type NoCommentsModule = {
  analyzeSource: (input: { source: string; relPath: string; precedentRegistry: unknown }) => {
    violations: Violation[];
  };
  loadPrecedentRegistry: (repoRoot: string) => unknown;
};

async function predicateViolations(fixture: string): Promise<Violation[]> {
  const moduleUrl = pathToFileURL(join(REPO_ROOT, 'lint-plugins/no-comments/index.mjs')).href;
  const { analyzeSource, loadPrecedentRegistry } = (await import(
    /* @vite-ignore */ moduleUrl
  )) as NoCommentsModule;
  const relPath = `${FIXTURE_DIR}/${fixture}`;
  return analyzeSource({
    source: readFileSync(join(REPO_ROOT, relPath), 'utf-8'),
    relPath,
    precedentRegistry: loadPrecedentRegistry(REPO_ROOT),
  }).violations;
}

const PARITY_FIXTURES = [
  'must-fire.fixture.ts',
  'must-not-fire.fixture.ts',
  'jsx-text.fixture.tsx',
  'jsdoc-types.fixture.mjs',
  'jsdoc-types.fixture.ts',
];

const runs = new Map<string, Run>();

beforeAll(async () => {
  runOxlintHelper = await loadRunOxlint();
  for (const fixture of [
    ...PARITY_FIXTURES,
    'suppression-blind.fixture.ts',
    'line-terminators.fixture.ts',
  ]) {
    runs.set(fixture, runOxlint(ALL_SCOPE_CONFIG, fixture));
  }
  runs.set('declared-scope', runOxlint(DECLARED_SCOPE_CONFIG, 'must-fire.fixture.ts'));
});

function run(key: string): Run {
  const value = runs.get(key);
  if (!value) throw new Error(`no oxlint run recorded for ${key}`);
  return value;
}

describe('no-comments oxlint plugin', () => {
  test('fires once per non-allowlisted comment, naming the class, the fix and the docs anchor', () => {
    const { status, diagnostics, raw } = run('must-fire.fixture.ts');
    expect(status).toBe(1);
    expect(diagnostics).toHaveLength(31);

    const classes = diagnostics.map((d) => d.class);
    expect(classes).toStrictEqual([
      'prose',
      'prose',
      'prose',
      'prose',
      'banned-directive',
      'prose',
      'unreasoned-directive',
      'invalid-upstream-referent',
      'rot-in-survivor',
      'unreasoned-directive',
      'prose',
      'prose',
      'prose',
      'prose',
      'prose',
      'prose',
      'prose',
      'prose',
      'prose',
      'prose',
      'prose',
      'prose',
      'prose',
      'prose',
      'prose',
      'prose',
      'prose',
      'prose',
      'prose',
      'prose',
      'prose',
    ]);

    expect(diagnostics.map((d) => d.line)).toStrictEqual([
      1, 4, 12, 15, 18, 21, 24, 27, 30, 33, 36, 39, 42, 47, 53, 56, 59, 63, 66, 69, 72, 75, 78, 81,
      87, 93, 96, 99, 102, 104, 106,
    ]);

    expect(raw).toContain(
      'Delete it. Put the reasoning in the commit message, the PR body, AGENTS.md, or the spec.',
    );
    expect(raw).toContain('Use `@ts-expect-error <reason>`');
    expect(raw).toContain('Use a resolvable referent');
    for (const diagnostic of diagnostics) {
      expect(diagnostic.message).toMatch(
        /See https:\/\/github\.com\/inkeep\/open-knowledge\/blob\/main\/lint-plugins\/no-comments\/README\.md#[a-z-]+$/,
      );
    }
  });

  test('stays silent on every allowlist class', () => {
    const { status, diagnostics } = run('must-not-fire.fixture.ts');
    expect(diagnostics).toStrictEqual([]);
    expect(status).toBe(0);
  });

  test('renders positions from the linter line map: U+2028 inside a string does not shift the squiggle', () => {
    const { diagnostics } = run('line-terminators.fixture.ts');
    expect(diagnostics).toHaveLength(1);
    expect(diagnostics[0]?.line).toBe(3);
    expect(diagnostics[0]?.column).toBe(1);
  });

  test('reads JSX text as text and a JSX expression comment as a comment', () => {
    const { diagnostics } = run('jsx-text.fixture.tsx');
    expect(diagnostics).toHaveLength(1);
    expect(diagnostics[0]?.line).toBe(5);
  });

  test('a rule disable silences this lane, which is why the backstop sweep exists', () => {
    const { status, diagnostics } = run('suppression-blind.fixture.ts');
    expect(diagnostics).toStrictEqual([]);
    expect(status).toBe(0);
  });

  test('leaves the fixture corpus alone under the declared scope, so a whole-tree lint stays quiet', () => {
    const { status, diagnostics } = run('declared-scope');
    expect(diagnostics).toStrictEqual([]);
    expect(status).toBe(0);
  });

  test('agrees with the shared predicate on every fixture, class for class and line for line', async () => {
    const compared: Record<string, number> = {};
    for (const fixture of PARITY_FIXTURES) {
      const { diagnostics, raw } = run(fixture);
      const violations = await predicateViolations(fixture);
      expect(raw, fixture).toContain('"number_of_files": 1');
      expect(diagnostics.map((d) => `${d.line}:${d.column}:${d.class}`)).toStrictEqual(
        violations.map((v) => `${v.comment.line}:${v.comment.column}:${v.class}`),
      );
      compared[fixture] = violations.length;
    }
    expect(compared).toStrictEqual({
      'must-fire.fixture.ts': 31,
      'must-not-fire.fixture.ts': 0,
      'jsx-text.fixture.tsx': 1,
      'jsdoc-types.fixture.mjs': 0,
      'jsdoc-types.fixture.ts': 3,
    });
  });

  test('the same JSDoc type block is a directive in .mjs and prose in .ts', () => {
    expect(run('jsdoc-types.fixture.mjs').diagnostics).toStrictEqual([]);
    expect(
      run('jsdoc-types.fixture.ts').diagnostics.map((d) => `${d.line}:${d.class}`),
    ).toStrictEqual(['1:prose', '4:prose', '12:prose']);
  });

  test('is registered in the repo oxlint config as a JS plugin with a staged severity', async () => {
    const config = (await import('../../../../oxlint.config')).default as {
      jsPlugins?: string[];
      rules?: Record<string, unknown>;
    };
    expect(config.jsPlugins).toContain(PLUGIN_REL);
    expect(Object.keys(config.rules ?? {})).toContain(RULE_ID);
    expect(['off', 'error']).toContain(config.rules?.[RULE_ID]);
  });

  test('loads from the path the shipped config names, not just the one the fixtures name', () => {
    const result = spawnSync(
      OXLINT_BIN,
      ['--max-warnings', '0', 'lint-plugins/no-comments/index.mjs'],
      {
        cwd: REPO_ROOT,
        encoding: 'utf-8',
      },
    );
    const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`;
    if (result.error) throw new Error(`oxlint did not run: ${result.error.message}\n${output}`);
    expect(output).not.toContain('Failed to load JS plugin');
    expect(output).not.toContain('Failed to load config');
    expect(output).not.toContain('Failed to parse');
    expect(result.status).toBe(0);
  });

  test('resolves a real repo path into declared scope, so the rule cannot go silently inert', async () => {
    const { relativePathFor } = await import('../../../../lint-plugins/no-comments/plugin.mjs');
    const { isInScope } = await import('../../../../lint-plugins/no-comments/scope.mjs');

    const absolute = join(REPO_ROOT, 'packages', 'core', 'src', 'index.ts');
    const relPath = relativePathFor({ physicalFilename: absolute });

    expect(relPath).toBe('packages/core/src/index.ts');
    expect(isInScope(relPath)).toBe(true);
    expect(relativePathFor({ filename: absolute })).toBe(relPath);
  });
});