Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

8.9 KB
Raw Blame
import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { basename, dirname, join, relative, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { type ParseError, parse as parseJsonc, printParseErrorCode } from 'jsonc-parser';
import { describe, expect, onTestFinished, test } from 'vitest';
import {
  CALLER_SUFFIX,
  HELPER_SUFFIX,
  SERVER_DIR,
  CALLERS_TSCONFIG as TSCONFIG,
} from './test-helper-caller-typecheck-coverage.reads.ts';

const OK_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
const PACKAGE_ROOT = resolve(OK_ROOT, SERVER_DIR);
const TYPECHECK_SCRIPT = 'typecheck:test-helper-callers';

const HELPERS = [
  'wait-within-test-budget.test-helper.ts',
  'expect-stable.test-helper.ts',
  'forked-watcher-process.test-helper.ts',
  'process-scan.test-helper.ts',
];

const UNSCANNED_DIRS = new Set(['node_modules', 'dist', '.turbo']);
const UNSCANNED_DIR_PREFIXES = ['.ok-skill-publish-'];

const isUnscanned = (name: string): boolean =>
  UNSCANNED_DIRS.has(name) || UNSCANNED_DIR_PREFIXES.some((prefix) => name.startsWith(prefix));

const RELATIVE_SPECIFIER = /(?:\bfrom|\bimport\s*\()\s*'(\.{1,2}\/[^']*)'/g;

function withoutTsExtension(specifier: string): string {
  return specifier.replace(/\.ts$/, '');
}

function importsAHelper(source: string): boolean {
  return [...source.matchAll(RELATIVE_SPECIFIER)].some((match) => {
    const specifier = withoutTsExtension(match[1] ?? '');
    return HELPERS.some((helper) => specifier.endsWith(`/${withoutTsExtension(helper)}`));
  });
}

function filesUnder(dir: string, suffix: string): string[] {
  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
    const path = join(dir, entry.name);
    if (entry.isDirectory()) {
      return isUnscanned(entry.name) ? [] : filesUnder(path, suffix);
    }
    return entry.isFile() && entry.name.endsWith(suffix) ? [path] : [];
  });
}

function callersOnDisk(): string[] {
  return filesUnder(PACKAGE_ROOT, CALLER_SUFFIX)
    .filter((path) => importsAHelper(readFileSync(path, 'utf8')))
    .map((path) => relative(PACKAGE_ROOT, path).replaceAll('\\', '/'))
    .sort();
}

function helpersOnDisk(root: string = PACKAGE_ROOT): string[] {
  return filesUnder(root, HELPER_SUFFIX).map((path) => basename(path));
}

function isStringArray(value: unknown): value is string[] {
  return Array.isArray(value) && value.every((item) => typeof item === 'string');
}

function namedIn(source: string): string[] {
  const errors: ParseError[] = [];
  const config = parseJsonc(source, errors, { allowTrailingComma: true }) as unknown;
  const parseError = errors[0];
  if (parseError !== undefined) {
    throw new Error(
      `${TSCONFIG} did not parse: ${printParseErrorCode(parseError.error)} at offset ` +
        `${parseError.offset}. jsonc-parser recovers past the damage and returns a partial ` +
        'value, so reading on would compare the callers on disk against whatever survived ' +
        'rather than against what the file declares, and report the difference as caller drift.',
    );
  }
  const files: unknown = (config as { files?: unknown } | null)?.files;
  if (!isStringArray(files)) {
    throw new Error(
      `${TSCONFIG} must declare files as an array of strings, the shape tsc requires: a ` +
        'different shape draws no parse error at all, and spreading it yields either nothing ' +
        'or a string split into its characters, which reads as every caller being unnamed.',
    );
  }
  return [...files].sort();
}

function namedInConfig(): string[] {
  return namedIn(readFileSync(resolve(PACKAGE_ROOT, TSCONFIG), 'utf8'));
}

function packageScripts(): Record<string, string> {
  const manifest = JSON.parse(readFileSync(resolve(PACKAGE_ROOT, 'package.json'), 'utf8')) as {
    scripts?: Record<string, string>;
  };
  return manifest.scripts ?? {};
}

describe('every caller of a shared test-only helper sits inside a typecheck program', () => {
  test(`names in ${TSCONFIG} exactly the test files that import one`, () => {
    const callers = callersOnDisk();
    expect(
      callers.length,
      'no test file in this package imports either helper, so this contract is asserting nothing',
    ).toBeGreaterThan(0);
    const named = namedInConfig();
    expect(
      {
        unnamed: callers.filter((file) => !named.includes(file)),
        stale: named.filter((file) => !callers.includes(file)),
      },
      `tsconfig.json excludes **/*.test.ts, so ${TSCONFIG} is the only program that reads these ` +
        'call sites: an unnamed caller lets a breaking helper signature change pass every ' +
        'compiler, and a stale name is a caller the program can no longer find. A name in ' +
        'files is always in the program, so naming a caller also obliges it to typecheck: ' +
        'admit a helper to HELPERS once every file importing it compiles, and until then ' +
        'leave the helper local to the file that needs it rather than sharing it.',
    ).toEqual({ unnamed: [], stale: [] });
  });

  test(`reaches that program from the package typecheck script`, () => {
    const scripts = packageScripts();
    expect(
      scripts[TYPECHECK_SCRIPT] ?? '',
      `${TYPECHECK_SCRIPT} must compile ${TSCONFIG}`,
    ).toContain(`-p ${TSCONFIG}`);
    expect(
      scripts.typecheck ?? '',
      `${TSCONFIG} compiles nothing anyone runs unless typecheck chains ${TYPECHECK_SCRIPT}`,
    ).toContain(TYPECHECK_SCRIPT);
  });

  test('detects a helper import written without its .ts extension', () => {
    const importing = (specifier: string) => `import { waitWithinTestBudget } from '${specifier}';`;

    expect(importsAHelper(importing('./wait-within-test-budget.test-helper.ts'))).toBe(true);
    expect(
      importsAHelper(importing('./wait-within-test-budget.test-helper')),
      'moduleResolution "bundler" resolves an extensionless relative import, so a caller ' +
        'spelled that way must still be found or it escapes the program unnamed',
    ).toBe(true);
    expect(importsAHelper(importing('node:path'))).toBe(false);
  });

  test('finds a helper whatever depth it sits at, which is what HELPERS can name', () => {
    const root = mkdtempSync(join(tmpdir(), 'test-helper-scan-'));
    onTestFinished(() => rmSync(root, { recursive: true, force: true }));
    mkdirSync(join(root, 'nested', 'deeper'), { recursive: true });
    writeFileSync(join(root, 'flat.test-helper.ts'), '');
    writeFileSync(join(root, 'nested', 'deeper', 'buried.test-helper.ts'), '');

    expect(
      helpersOnDisk(root).sort(),
      'importsAHelper matches a helper by basename at any depth, so an existence scan that ' +
        'reads one directory level calls a nested helper missing and, through the assertion ' +
        'below, reports every caller of a helper that is present as already covered',
    ).toEqual(['buried.test-helper.ts', 'flat.test-helper.ts']);
  });

  test('skips the skill-bundle staging roots a server build leaves beside its sources', () => {
    const root = mkdtempSync(join(tmpdir(), 'test-helper-scan-'));
    onTestFinished(() => rmSync(root, { recursive: true, force: true }));
    const plant = (path: string) => {
      mkdirSync(join(root, dirname(path)), { recursive: true });
      writeFileSync(join(root, path), '');
    };
    plant('src/source.test.ts');
    plant('.ok-skill-publish-a1b2c3/assets/staged.test.ts');
    plant('.ok-skill-publish-kept-a1b2c3/staged.test.ts');

    expect(
      filesUnder(root, CALLER_SUFFIX).map((path) => relative(root, path).replaceAll('\\', '/')),
      'a staging root is gitignored and written by the server build, so it sits outside the ' +
        "cache key of the test task this walk runs in, and entering it reads the build's output",
    ).toEqual(['src/source.test.ts']);
  });

  test('names in HELPERS only helpers that are on disk', () => {
    const present = helpersOnDisk();
    expect(
      HELPERS.filter((helper) => !present.includes(helper)),
      'a helper renamed or removed leaves its entry matching nothing, and the guard then ' +
        'reports every caller of it as already covered',
    ).toEqual([]);
  });

  test(`reads ${TSCONFIG} the way tsc does, and tells a broken file from caller drift`, () => {
    expect(
      namedIn('{\n  // the callers\n  "files": ["src/b.test.ts", "src/a.test.ts",],\n}'),
      'tsc compiles a tsconfig carrying comments and trailing commas, so a reader stricter ' +
        'than tsc would red on a config that builds',
    ).toEqual(['src/a.test.ts', 'src/b.test.ts']);

    expect(() => namedIn('{"files": ["src/a.test.ts"')).toThrow(/did not parse/);
    expect(() => namedIn('{"files": "src/a.test.ts"}')).toThrow(/array of strings/);
    expect(
      () => namedIn('null'),
      'a bare null is valid JSON and draws no parse error, so without an object check the ' +
        'reader throws a raw TypeError from inside itself rather than either diagnostic it writes',
    ).toThrow(/array of strings/);
  });
});