Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

9.8 KB
Raw Blame
/**
 * The gate's own tests.
 *
 * Two of them are mandatory, and they are the reason this gate parses TypeScript
 * instead of grepping. Both traps make a naive gate report the wrong number:
 *
 *   trap 1  `rg 'export function create[A-Za-z]+Service\(deps'` finds 28 of the
 *           36 factories, because eight signatures span lines.
 *   trap 2  `rg -o 'ReturnType<typeof create' services.ts` matches once and the
 *           match is a COMMENT at services.ts:154; the pattern is applied in
 *           code zero times.
 *
 * The fixtures below contain exactly those shapes. A regression that reverts a
 * check to a line-oriented match fails here.
 */

import { describe, expect, test } from 'bun:test';
import { ASSET_LOADER_ALLOWLIST } from './conformance.constants';
import {
  checkCreateServicesCallSites,
  checkDependencyLoaders,
  checkFactorySignatures,
  checkModuleScopeConstruction,
  checkServicesMembers,
  collectEnvReads,
} from './rules';
import { parseSource } from './sources';

const NAIVE_FACTORY_GREP = /export function create[A-Za-z]+Service\(deps/g;
const NAIVE_RETURN_TYPE_GREP = /ReturnType<typeof create/g;

const matchCount = (text: string, pattern: RegExp): number =>
  (text.match(pattern) ?? []).length;

describe('trap 1 — a factory signature that spans lines', () => {
  // Three factories: one on a single line, one whose argument list starts on the
  // next line, and one already conformant. A line-oriented grep sees one.
  const source = `
import type { ServiceDeps, Services } from '../../services';

export function createOneLineService(deps: ServiceDeps) {
  return { a: () => deps };
}

export function createWrappedService(
  deps: ServiceDeps
) {
  return { b: () => deps };
}

export function createConformantService(
  deps: ServiceDeps,
  services: () => Services
) {
  return { c: () => services() };
}
`;

  test('the naive grep undercounts, which is why it is not the check', () => {
    expect(matchCount(source, NAIVE_FACTORY_GREP)).toBe(1);
  });

  test('the AST check sees all three factories', () => {
    const metric = checkFactorySignatures([
      parseSource('packages/core/src/modules/x/x.service.ts', source),
    ]);
    expect(metric.label).toContain('of 3');
  });

  test('it flags both non-conformant signatures, including the wrapped one', () => {
    const metric = checkFactorySignatures([
      parseSource('packages/core/src/modules/x/x.service.ts', source),
    ]);
    expect(metric.count).toBe(2);
    expect(metric.offenders.map((offender) => offender.detail)).toEqual([
      expect.stringContaining('createOneLineService'),
      expect.stringContaining('createWrappedService'),
    ]);
  });

  test('an arrow-function factory is counted too', () => {
    const arrows = `
import type { ServiceDeps } from '../../services';
export const createArrowService = (deps: ServiceDeps) => ({ a: () => deps });
`;
    const metric = checkFactorySignatures([
      parseSource('packages/core/src/modules/y/y.service.ts', arrows),
    ]);
    expect(metric.count).toBe(1);
  });
});

describe('trap 2 — ReturnType<typeof create...> in a comment', () => {
  // The comment is the shape of the real one at services.ts:154. One member is
  // typed by hand, one is typed the way R5 wants.
  const source = `
// Two type rules the compiler enforces but cannot explain:
//
// 1. \`Services\` must stay an INTERFACE. A type alias over
//    \`ReturnType<typeof createServices>\` is circular — resolving it needs
//    every factory's signature and every factory's signature names
//    \`Services\`.
export interface Services {
  auth: AuthService;
  chart: ReturnType<typeof createChartService>;
}
`;

  test('the naive grep counts the comment as a compliant member', () => {
    // Two matches for one real member: the grep cannot tell them apart.
    expect(matchCount(source, NAIVE_RETURN_TYPE_GREP)).toBe(2);
  });

  test('the AST check ignores the comment and counts only the real member', () => {
    const metric = checkServicesMembers([
      parseSource('packages/core/src/services.ts', source),
    ]);
    expect(metric.label).toContain('1 of 2');
    expect(metric.count).toBe(1);
    expect(metric.offenders[0].detail).toContain('auth: AuthService');
  });

  test('a file whose only match is the comment scores zero compliant members', () => {
    const commentOnly = `
// \`ReturnType<typeof createServices>\` is circular.
export interface Services {
  auth: AuthService;
}
`;
    const metric = checkServicesMembers([
      parseSource('packages/core/src/services.ts', commentOnly),
    ]);
    expect(matchCount(commentOnly, NAIVE_RETURN_TYPE_GREP)).toBe(1);
    expect(metric.label).toContain('0 of 1');
  });
});

describe('R6 — the asset-loader carve-out is an allowlist, not a pattern', () => {
  const geo = parseSource(
    'packages/core/src/clients/geo.ts',
    'async function loadDatabase(filename: string) { return filename; }\n'
  );
  const flushExports = parseSource(
    'packages/core/src/modules/integration/src/flush-exports.ts',
    'async function loadCursor(id: string) { return id; }\n'
  );

  test('the two allowlisted asset loaders are not offenders', () => {
    const metric = checkDependencyLoaders([geo, flushExports]);
    expect(metric.count).toBe(0);
    expect(metric.label).toContain('0 of 2 load* functions');
  });

  test('the allowlist is exactly the two sanctioned files, each with a reason', () => {
    expect(ASSET_LOADER_ALLOWLIST.map((entry) => entry.file)).toEqual([
      'packages/core/src/clients/geo.ts',
      'packages/core/src/modules/integration/src/flush-exports.ts',
    ]);
    for (const entry of ASSET_LOADER_ALLOWLIST) {
      expect(entry.reason.length).toBeGreaterThan(0);
    }
  });

  test('a NEW loader cannot join the allowlist by looking like one', () => {
    const impostor = parseSource(
      'packages/core/src/modules/other/src/thing.ts',
      'async function loadDatabase() { return null; }\n'
    );
    const metric = checkDependencyLoaders([impostor]);
    expect(metric.count).toBe(1);
  });

  test('the same name in the WRONG file is still an offender', () => {
    const wrongFile = parseSource(
      'packages/core/src/clients/geo-other.ts',
      'async function loadCursor() { return null; }\n'
    );
    expect(checkDependencyLoaders([wrongFile]).count).toBe(1);
  });
});

describe('R6 — createServices call sites', () => {
  test('a call in a comment or a string is not a call site', () => {
    const source = parseSource(
      'packages/core/src/modules/x/x.service.ts',
      `
// createServices( is built once per unit of work.
const documentation = 'call createServices( only at the sanctioned sites';
`
    );
    expect(checkCreateServicesCallSites([source]).count).toBe(0);
  });

  test('a real call outside the sanctioned sites is an offender', () => {
    const source = parseSource(
      'packages/core/src/v1-compat.ts',
      'const services = createServices(deps);\n'
    );
    expect(checkCreateServicesCallSites([source]).count).toBe(1);
  });

  test('the same call inside a sanctioned site is not', () => {
    const source = parseSource(
      'packages/core/src/context.ts',
      'const services = createServices(deps);\n'
    );
    expect(checkCreateServicesCallSites([source]).count).toBe(0);
  });
});

describe('R7 — process.env forms a `process.env.` grep gets wrong', () => {
  const source = parseSource(
    'packages/core/src/shared/get-client-ip.ts',
    `
// core reads no process.env.
const a = process.env.PLAIN;
const b = process.env?.OPTIONAL;
const c = process.env['BRACKETED'];
`
  );

  test('the comment is not a read and the optional-chained one is', () => {
    const { dotted, bracketed } = collectEnvReads([source]);
    expect(dotted.map((offender) => offender.detail)).toEqual([
      'process.env.PLAIN',
      'process.env.OPTIONAL',
    ]);
    expect(bracketed).toHaveLength(1);
  });

  test('the naive grep gets a different answer to the AST', () => {
    const grepped = matchCount(source.text, /process\.env\./g);
    // One comment counted, one `process.env?.` missed, one `process.env[` missed.
    expect(grepped).toBe(2);
  });
});

describe('R15 — the two constructor spellings modules/auth/src/oauth.ts uses', () => {
  // Both arctic clients, both correct: built per call, from config. The bug
  // this guards against was in the checker, not this file — `GitHub` was not
  // in the constructor set and `Arctic.Google` is a property access an
  // `ts.isIdentifier` guard cannot see at all.
  const oauthShape = `
import * as Arctic from 'arctic';
import { GitHub } from 'arctic';

export function githubClient(config: CoreConfig): GitHub {
  return new GitHub(config.id, config.secret, config.redirect);
}

export function googleClient(config: CoreConfig): Arctic.Google {
  return new Arctic.Google(config.id, config.secret, config.redirect);
}
`;

  test('inside a factory body, neither is a violation', () => {
    const source = parseSource(
      'packages/core/src/modules/auth/src/oauth.ts',
      oauthShape
    );
    expect(checkModuleScopeConstruction([source]).count).toBe(0);
  });

  test('a connection nested in another constructor still counts', () => {
    const source = parseSource(
      'packages/core/src/buffers/event-buffer.ts',
      'const buffer = new Wrapper(new Redis(url));\n'
    );
    expect(checkModuleScopeConstruction([source]).count).toBe(1);
  });

  test('at module scope, BOTH are — the qualified one included', () => {
    const source = parseSource(
      'packages/core/src/modules/auth/src/oauth.ts',
      `
const github = new GitHub(id, secret, redirect);
const google = new Arctic.Google(id, secret, redirect);
`
    );
    const metric = checkModuleScopeConstruction([source]);
    expect(metric.count).toBe(2);
    expect(metric.offenders.map((offender) => offender.detail)).toEqual([
      'new GitHub( at module scope',
      'new Arctic.Google( at module scope',
    ]);
  });
});