api-content-quality.test.ts

import { readdirSync, readFileSync } from 'node:fs';
import { join, relative } from 'node:path';

import { describe, expect, it } from 'vitest';

const PROJECT_ROOT = process.cwd();
const API_REFERENCE_DIR = join(PROJECT_ROOT, 'api-reference');
const FRONTMATTER_API_PATTERN = /^api:\s*"([A-Z]+) ([^"]+)"/mu;
const UNIX_TIMESTAMP_FILTER_ENDPOINTS: ReadonlySet<string> = new Set([
  'GET /x/lists/{id}/tweets',
  'GET /x/tweets/{id}/quotes',
  'GET /x/tweets/{id}/replies',
  'GET /x/users/{id}/mentions',
] as const);
const FORBIDDEN_PUBLIC_ENDPOINT_SNIPPETS = [
  ['shared', 'read', 'pool'].join(' '),
  ['read', 'pool'].join(' '),
  ['participant', 'session'].join(' '),
  ['session', 'reads', 'the', 'conversation'].join(' '),
  ['whose', 'session', 'reads'].join(' '),
  'A transient upstream issue occurred. Safe to retry with exponential backoff.',
  'The X data source returned an error. Retry after a short delay.',
  'The best-practice response contract can return 424 when the upstream X data source fails.',
  'Returned when you opt into the normalized v1 response contract and the upstream dependency fails.',
  'The X data source is temporarily unavailable. Retry with exponential backoff.',
] as const;

interface ContentFinding {
  readonly file: string;
  readonly issue: string;
}

function listApiReferenceFiles(dir: string): readonly string[] {
  const files: string[] = [];
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
    const fullPath = join(dir, entry.name);
    if (entry.isDirectory()) {
      files.push(...listApiReferenceFiles(fullPath));
      continue;
    }
    if (entry.name.endsWith('.mdx')) {
      files.push(relative(PROJECT_ROOT, fullPath));
    }
  }
  return files.sort();
}

function isApiEndpointPage(source: string): boolean {
  return FRONTMATTER_API_PATTERN.test(source);
}

function operationKey(source: string): string | undefined {
  const match = FRONTMATTER_API_PATTERN.exec(source);
  if (match?.[1] === undefined || match[2] === undefined) {
    return undefined;
  }
  return `${match[1]} ${match[2]}`;
}

function collectContentFindings(): readonly ContentFinding[] {
  const findings: ContentFinding[] = [];

  for (const file of listApiReferenceFiles(API_REFERENCE_DIR)) {
    const source = readFileSync(join(PROJECT_ROOT, file), 'utf8');
    if (!isApiEndpointPage(source)) {
      continue;
    }

    if (!source.includes('<CodeGroup>')) {
      findings.push({ file, issue: 'Missing copy-ready code examples.' });
    }

    if (!/^## Headers\b/mu.test(source)) {
      findings.push({ file, issue: 'Missing headers section.' });
    }

    if (!/^## Response\b/mu.test(source)) {
      findings.push({ file, issue: 'Missing response section.' });
    }

    if (!/<Tab title="2\d\d\b/u.test(source)) {
      findings.push({ file, issue: 'Missing successful response tab.' });
    }

    const key = operationKey(source);
    for (const snippet of FORBIDDEN_PUBLIC_ENDPOINT_SNIPPETS) {
      if (source.includes(snippet)) {
        findings.push({
          file,
          issue: `Public endpoint page exposes internal wording "${snippet}".`,
        });
      }
    }

    if (
      key !== undefined &&
      UNIX_TIMESTAMP_FILTER_ENDPOINTS.has(key) &&
      source.includes('ISO 8601 timestamp')
    ) {
      findings.push({
        file,
        issue: 'sinceTime/untilTime must document Unix timestamp filters.',
      });
    }
  }

  return findings;
}

describe('API endpoint content quality', (): void => {
  it('keeps endpoint pages useful beyond generated signatures', (): void => {
    expect.assertions(1);

    expect(collectContentFindings()).toStrictEqual([]);
  });
});