tstyche 1.0.0-beta.0

package/build/tstyche.d.ts

@@ -0,0 +1,679 @@
+/// <reference types="node" resolution-mode="require"/>
+
+import type ts from 'typescript/lib/tsserverlibrary.js';
+
+declare enum DiagnosticCategory {
+    Error = "error",
+    Warning = "warning"
+}
+
+interface DiagnosticOrigin {
+    breadcrumbs?: Array<string>;
+    end: number;
+    file: ts.SourceFile;
+    start: number;
+}
+declare class Diagnostic {
+    #private;
+    text: string | Array<string>;
+    category: DiagnosticCategory;
+    origin?: DiagnosticOrigin | undefined;
+    code?: string;
+    related?: Array<Diagnostic>;
+    constructor(text: string | Array<string>, category: DiagnosticCategory, origin?: DiagnosticOrigin | undefined);
+    add(options: {
+        code?: string;
+        related?: Array<Diagnostic>;
+    }): this;
+    static error(text: string | Array<string>, origin?: DiagnosticOrigin): Diagnostic;
+    static fromDiagnostics(diagnostics: ReadonlyArray<ts.Diagnostic>, compiler: typeof ts): Array<Diagnostic>;
+    static fromError(text: string | Array<string>, error: unknown): Diagnostic;
+    static isTsDiagnosticWithLocation(diagnostic: ts.Diagnostic): diagnostic is ts.DiagnosticWithLocation;
+    static warning(text: string | Array<string>, origin?: DiagnosticOrigin): Diagnostic;
+}
+
+declare class StoreService {
+    #private;
+    constructor();
+    getSupportedTags(): Array<string>;
+    loadCompilerModule(tag: string, signal?: AbortSignal): Promise<typeof ts | undefined>;
+    open(signal?: AbortSignal): Promise<void>;
+    prepareCompilerModule(tag: string, signal?: AbortSignal): Promise<string | undefined>;
+    prune(): Promise<void>;
+    resolveTag(tag: string): string | undefined;
+    update(signal?: AbortSignal): Promise<void>;
+    validateTag(tag: string): boolean;
+}
+
+interface TypeChecker extends ts.TypeChecker {
+    isTypeAssignableTo?: (source: ts.Type, target: ts.Type) => boolean;
+    isTypeIdenticalTo?: (source: ts.Type, target: ts.Type) => boolean;
+    isTypeSubtypeOf?: (source: ts.Type, target: ts.Type) => boolean;
+}
+
+declare enum OptionBrand {
+    String = "string",
+    Number = "number",
+    Boolean = "boolean",
+    List = "list",
+    Object = "object"
+}
+
+declare enum OptionGroup {
+    CommandLine = 2,
+    ConfigFile = 4
+}
+
+interface ItemDefinition {
+    brand: OptionBrand.String | OptionBrand.Object;
+    getDefinition?: (optionGroup: OptionGroup) => Map<string, OptionDefinition>;
+    name: string;
+    nullable?: boolean;
+    pattern?: string;
+    properties?: Array<OptionDefinition>;
+}
+type OptionDefinition = PrimitiveTypeOptionDefinition | ListTypeOptionDefinition | ObjectTypeOptionDefinition;
+interface BaseOptionDefinition {
+    brand: OptionBrand;
+    description: string;
+    group: OptionGroup;
+    name: string;
+    nullable?: boolean;
+    required?: boolean;
+}
+interface PrimitiveTypeOptionDefinition extends BaseOptionDefinition {
+    brand: OptionBrand.String | OptionBrand.Number | OptionBrand.Boolean;
+}
+interface ListTypeOptionDefinition extends BaseOptionDefinition {
+    brand: OptionBrand.List;
+    items: ItemDefinition;
+}
+interface ObjectTypeOptionDefinition extends BaseOptionDefinition {
+    brand: OptionBrand.Object;
+    getDefinition: (optionGroup: OptionGroup) => Map<string, OptionDefinition>;
+    properties: Array<OptionDefinition>;
+}
+declare class OptionDefinitionsMap {
+    #private;
+    static for(optionGroup: OptionGroup): Map<string, OptionDefinition>;
+}
+
+/**
+ * Options passed through the command line.
+ */
+interface CommandLineOptions {
+    /**
+     * Do not raise an error, if no test files are selected.
+     */
+    allowNoTestFiles?: boolean;
+    /**
+     * The path to a TSTyche configuration file.
+     */
+    config?: string;
+    /**
+     * Stop running tests after the first failed assertion.
+     */
+    failFast?: boolean;
+    /**
+     * Print the list of CLI options with brief descriptions and exit.
+     */
+    help?: boolean;
+    /**
+     * Install specified versions of the 'typescript' package and exit.
+     */
+    install?: boolean;
+    /**
+     * Print the list of the selected test files and exit.
+     */
+    listFiles?: boolean;
+    /**
+     * Only run tests with matching name.
+     */
+    only?: string;
+    /**
+     * Remove all installed versions of the 'typescript' package and exit.
+     */
+    prune?: boolean;
+    /**
+     * Print the resolved configuration and exit.
+     */
+    showConfig?: boolean;
+    /**
+     * Skip tests with matching name.
+     */
+    skip?: string;
+    /**
+     * The list of TypeScript versions to be tested on.
+     */
+    target?: Array<string>;
+    /**
+     * Fetch the 'typescript' package metadata from the registry and exit.
+     */
+    update?: boolean;
+    /**
+     * Print the version number and exit.
+     */
+    version?: boolean;
+}
+
+/**
+ * Options loaded from the configuration file.
+ */
+interface ConfigFileOptions {
+    /**
+     * Do not raise an error, if no test files are selected.
+     */
+    allowNoTestFiles?: boolean;
+    /**
+     * Stop running tests after the first failed assertion.
+     */
+    failFast?: boolean;
+    /**
+     * The path to a directory containing files of a test project.
+     */
+    rootPath?: string;
+    /**
+     * The list of TypeScript versions to be tested on.
+     */
+    target?: Array<string>;
+    /**
+     * The list of glob patterns matching the test files.
+     */
+    testFileMatch?: Array<string>;
+}
+
+interface ResolvedConfig extends Omit<CommandLineOptions, keyof ConfigFileOptions>, Required<ConfigFileOptions> {
+    /**
+     * Only run test files with matching path.
+     */
+    pathMatch: Array<string>;
+}
+declare class ConfigService {
+    #private;
+    compiler: typeof ts;
+    constructor(compiler: typeof ts, storeService: StoreService);
+    get commandLineOptions(): CommandLineOptions;
+    get configFileOptions(): ConfigFileOptions;
+    static get defaultOptions(): Required<ConfigFileOptions>;
+    parseCommandLine(commandLineArgs: Array<string>): void;
+    readConfigFile(filePath?: string, // TODO take URL as well
+    sourceText?: string): Promise<void>;
+    resolveConfig(): ResolvedConfig;
+    selectTestFiles(): Array<string>;
+}
+
+declare class TSTyche {
+    #private;
+    readonly resolvedConfig: ResolvedConfig;
+    constructor(resolvedConfig: ResolvedConfig, storeService: StoreService);
+    static get version(): string;
+    run(testFiles: Array<string | URL>): Promise<void>;
+}
+
+declare enum AssertionSource {
+    Argument = 0,
+    TypeArgument = 1
+}
+
+declare enum TestMemberBrand {
+    Describe = "describe",
+    Test = "test",
+    Expect = "expect"
+}
+
+declare enum TestMemberFlags {
+    None = 0,
+    Fail = 1,
+    Only = 2,
+    Skip = 4,
+    Todo = 8
+}
+
+declare class TestTree {
+    compiler: typeof ts;
+    diagnostics: Array<ts.Diagnostic>;
+    sourceFile: ts.SourceFile;
+    typeChecker?: TypeChecker | undefined;
+    members: Array<TestMember | Assertion>;
+    constructor(compiler: typeof ts, diagnostics: Array<ts.Diagnostic>, sourceFile: ts.SourceFile, typeChecker?: TypeChecker | undefined);
+    get hasOnly(): boolean;
+}
+
+declare class TestMember {
+    #private;
+    brand: TestMemberBrand;
+    node: ts.CallExpression;
+    parent: TestTree | TestMember;
+    flags: TestMemberFlags;
+    compiler: typeof ts;
+    diagnostics: Array<ts.Diagnostic>;
+    members: Array<TestMember | Assertion>;
+    name: string;
+    typeChecker?: TypeChecker | undefined;
+    constructor(brand: TestMemberBrand, node: ts.CallExpression, parent: TestTree | TestMember, flags: TestMemberFlags);
+    get ancestorNames(): Array<string>;
+    validate(): Array<Diagnostic>;
+}
+
+interface MatcherNode extends ts.CallExpression {
+    expression: ts.PropertyAccessExpression;
+}
+declare class Assertion extends TestMember {
+    #private;
+    matcherNode: MatcherNode;
+    modifierNode: ts.PropertyAccessExpression;
+    notNode: ts.PropertyAccessExpression | undefined;
+    isNot: boolean;
+    name: string;
+    constructor(brand: TestMemberBrand, node: ts.CallExpression, parent: TestTree | TestMember, flags: TestMemberFlags, matcherNode: MatcherNode, modifierNode: ts.PropertyAccessExpression, notNode: ts.PropertyAccessExpression | undefined);
+    get ancestorNames(): Array<string>;
+    get matcherName(): ts.MemberName;
+    get sourceArguments(): ts.NodeArray<ts.Expression>;
+    get sourceType(): {
+        source: AssertionSource;
+        type: ts.Type;
+    } | undefined;
+    get targetArguments(): ts.NodeArray<ts.Expression>;
+    get targetType(): {
+        source: AssertionSource;
+        type: ts.Type;
+    } | undefined;
+}
+
+declare class CollectService {
+    #private;
+    compiler: typeof ts;
+    readonly matcherIdentifiers: string[];
+    readonly modifierIdentifiers: string[];
+    readonly notIdentifier = "not";
+    constructor(compiler: typeof ts);
+    createTestTree(sourceFile: ts.SourceFile, semanticDiagnostics?: Array<ts.Diagnostic>, typeChecker?: ts.TypeChecker | undefined): TestTree;
+}
+
+declare class Checker {
+    #private;
+    compiler: typeof ts;
+    constructor(compiler: typeof ts);
+    explain(assertion: Assertion): Array<Diagnostic>;
+    match(assertion: Assertion): boolean;
+}
+
+declare class Cli {
+    #private;
+    constructor(process: NodeJS.Process);
+    run(commandLineArgs: Array<string>): Promise<void>;
+}
+
+declare class Environment {
+    #private;
+    /**
+     * Specifies whether color should be disabled in the output.
+     */
+    static get noColor(): boolean;
+    /**
+     * The directory where to store the 'typescript' packages.
+     */
+    static get storePath(): string;
+    /**
+     * The number of seconds to wait before giving up stale operations.
+     */
+    static get timeout(): number;
+}
+
+declare class ResultTiming {
+    end: number;
+    start: number;
+    get duration(): number;
+}
+
+type FileResultStatus = ResultStatus.Runs | ResultStatus.Passed | ResultStatus.Failed;
+declare enum ResultStatus {
+    Runs = "runs",
+    Passed = "passed",
+    Failed = "failed",
+    Skipped = "skipped",
+    Todo = "todo"
+}
+
+declare class ExpectResult {
+    assertion: Assertion;
+    parent: TestResult | undefined;
+    diagnostics: Array<Diagnostic>;
+    status: ResultStatus;
+    timing: ResultTiming;
+    constructor(assertion: Assertion, parent: TestResult | undefined);
+}
+
+declare class ResultCount {
+    failed: number;
+    passed: number;
+    skipped: number;
+    todo: number;
+    get total(): number;
+}
+
+declare class TestResult {
+    test: TestMember;
+    parent: DescribeResult | undefined;
+    diagnostics: Array<Diagnostic>;
+    expectCount: ResultCount;
+    results: Array<ExpectResult>;
+    status: ResultStatus;
+    timing: ResultTiming;
+    constructor(test: TestMember, parent: DescribeResult | undefined);
+}
+
+declare class DescribeResult {
+    describe: TestMember;
+    parent: DescribeResult | undefined;
+    results: Array<DescribeResult | TestResult>;
+    timing: ResultTiming;
+    constructor(describe: TestMember, parent: DescribeResult | undefined);
+}
+
+declare class FileResult {
+    testFile: URL;
+    diagnostics: Array<Diagnostic>;
+    expectCount: ResultCount;
+    results: Array<DescribeResult | TestResult | ExpectResult>;
+    status: FileResultStatus;
+    testCount: ResultCount;
+    timing: ResultTiming;
+    constructor(testFile: URL);
+}
+
+declare class ProjectResult {
+    compilerVersion: string;
+    projectConfigFilePath: string | undefined;
+    diagnostics: Array<Diagnostic>;
+    results: Array<FileResult>;
+    constructor(compilerVersion: string, projectConfigFilePath: string | undefined);
+}
+
+declare class TargetResult {
+    versionTag: string;
+    testFiles: Array<URL>;
+    results: Map<string | undefined, ProjectResult>;
+    status: ResultStatus.Runs | ResultStatus.Passed | ResultStatus.Failed;
+    timing: ResultTiming;
+    constructor(versionTag: string, testFiles: Array<URL>);
+}
+
+declare class Result {
+    resolvedConfig: ResolvedConfig;
+    testFiles: Array<URL>;
+    expectCount: ResultCount;
+    fileCount: ResultCount;
+    results: Array<TargetResult>;
+    targetCount: ResultCount;
+    testCount: ResultCount;
+    timing: ResultTiming;
+    constructor(resolvedConfig: ResolvedConfig, testFiles: Array<URL>);
+}
+
+declare class ResultManager {
+    #private;
+    handleEvent([eventName, payload]: Event): void;
+}
+
+type Event = ["start", {
+    result: Result;
+}] | ["end", {
+    result: Result;
+}] | ["config:error", {
+    diagnostics: Array<Diagnostic>;
+}] | ["store:info", {
+    compilerVersion: string;
+    installationPath: string;
+}] | ["store:error", {
+    diagnostics: Array<Diagnostic>;
+}] | ["target:start", {
+    result: TargetResult;
+}] | ["target:end", {
+    result: TargetResult;
+}] | ["project:info", {
+    compilerVersion: string;
+    projectConfigFilePath: string | undefined;
+}] | ["project:error", {
+    diagnostics: Array<Diagnostic>;
+}] | ["file:start", {
+    result: FileResult;
+}] | ["file:error", {
+    diagnostics: Array<Diagnostic>;
+    result: FileResult;
+}] | ["file:end", {
+    result: FileResult;
+}] | ["describe:start", {
+    result: DescribeResult;
+}] | ["describe:end", {
+    result: DescribeResult;
+}] | ["test:start", {
+    result: TestResult;
+}] | ["test:error", {
+    diagnostics: Array<Diagnostic>;
+    result: TestResult;
+}] | ["test:fail", {
+    result: TestResult;
+}] | ["test:pass", {
+    result: TestResult;
+}] | ["test:skip", {
+    result: TestResult;
+}] | ["test:todo", {
+    result: TestResult;
+}] | ["expect:start", {
+    result: ExpectResult;
+}] | ["expect:error", {
+    diagnostics: Array<Diagnostic>;
+    result: ExpectResult;
+}] | ["expect:fail", {
+    diagnostics: Array<Diagnostic>;
+    result: ExpectResult;
+}] | ["expect:pass", {
+    result: ExpectResult;
+}] | ["expect:skip", {
+    result: ExpectResult;
+}];
+type EventHandler = (event: Event) => void;
+declare class EventEmitter {
+    #private;
+    static addHandler(handler: EventHandler): void;
+    static dispatch(event: Event): void;
+    static removeHandler(handler: EventHandler): void;
+}
+
+/**
+ * Options to configure an instance of the {@link Logger}.
+ */
+interface LoggerOptions {
+    /**
+     * Specifies whether color should be disabled in the output. Default: `Environment.noColor`.
+     */
+    noColor?: boolean;
+    /**
+     * A stream to write warnings and errors. Default: `process.stdout`.
+     */
+    stderr?: NodeJS.WritableStream;
+    /**
+     * A stream to write informational messages. Default: `process.stderr`.
+     */
+    stdout?: NodeJS.WritableStream;
+}
+/**
+ * Wraps the provided streams with a set of convenience methods.
+ */
+declare class Logger {
+    #private;
+    /**
+     * @param options - {@link LoggerOptions | Options} to configure an instance of the Logger.
+     */
+    constructor(options?: LoggerOptions);
+    /**
+     * Moves the cursor one line up and erases the line when the `stdout` stream
+     * is interactive. Otherwise does nothing.
+     */
+    eraseLastLine(): void;
+    /**
+     * Returns `true` if the `stdout` stream is interactive.
+     */
+    isInteractive(): boolean;
+    writeError(body: JSX.Element | Array<JSX.Element>): void;
+    writeMessage(body: JSX.Element | Array<JSX.Element>): void;
+    writeWarning(body: JSX.Element | Array<JSX.Element>): void;
+}
+
+declare class ProjectService {
+    #private;
+    compiler: typeof ts;
+    constructor(compiler: typeof ts);
+    closeFile(filePath: string): void;
+    getDefaultProject(filePath: string): ts.server.Project | undefined;
+    getLanguageService(filePath: string): ts.LanguageService | undefined;
+    openFile(filePath: string, sourceText?: string | undefined, projectRootPath?: string | undefined): void;
+}
+
+declare abstract class Reporter {
+    readonly resolvedConfig: ResolvedConfig;
+    protected logger: Logger;
+    constructor(resolvedConfig: ResolvedConfig);
+    abstract handleEvent([eventName, payload]: Event): void;
+}
+
+declare class SummaryReporter extends Reporter {
+    handleEvent([eventName, payload]: Event): void;
+}
+
+declare class ThoroughReporter extends Reporter {
+    #private;
+    handleEvent([eventName, payload]: Event): void;
+}
+
+declare class TaskRunner {
+    #private;
+    readonly resolvedConfig: ResolvedConfig;
+    constructor(resolvedConfig: ResolvedConfig, storeService: StoreService);
+    run(testFiles: Array<URL>, target: Array<string>, signal?: AbortSignal): Promise<Result>;
+}
+
+declare enum Color {
+    Reset = "0",
+    Red = "31",
+    Green = "32",
+    Yellow = "33",
+    Blue = "34",
+    Magenta = "35",
+    Cyan = "36",
+    Gray = "90"
+}
+
+declare function addsPackageStepText(compilerVersion: string, installationPath: string): JSX.Element;
+
+declare function describeNameText(name: string, indent?: number): JSX.Element;
+
+declare function diagnosticText(diagnostic: Diagnostic): JSX.Element;
+
+declare function fileStatusText(status: FileResultStatus, testFile: URL): JSX.Element;
+
+declare function fileViewText(lines: Array<JSX.Element>, addEmptyFinalLine: boolean): JSX.Element;
+
+interface LineProps {
+    children?: JSX.ElementChildrenAttribute["children"];
+    color?: Color;
+    indent?: number;
+}
+declare class Line implements JSX.ElementClass {
+    readonly props: LineProps;
+    constructor(props: LineProps);
+    render(): JSX.Element;
+}
+
+declare function summaryText({ duration, expectCount, fileCount, onlyMatch, pathMatch, skipMatch, targetCount, testCount, }: {
+    duration: number;
+    expectCount: ResultCount;
+    fileCount: ResultCount;
+    onlyMatch: string | undefined;
+    pathMatch: Array<string>;
+    skipMatch: string | undefined;
+    targetCount: ResultCount;
+    testCount: ResultCount;
+}): JSX.Element;
+
+declare function testNameText(status: "fail" | "pass" | "skip" | "todo", name: string, indent?: number): JSX.Element;
+
+interface TextProps {
+    children?: JSX.ElementChildrenAttribute["children"];
+    color?: Color | undefined;
+    indent?: number | undefined;
+}
+declare class Text implements JSX.ElementClass {
+    readonly props: TextProps;
+    constructor(props: TextProps);
+    render(): JSX.Element;
+}
+
+declare function usesCompilerStepText(compilerVersion: string, tsconfigFilePath: string | undefined, options?: {
+    prependEmptyLine: boolean;
+}): JSX.Element;
+
+type ElementChildren = Array<ElementChildren> | JSX.Element | string | undefined;
+type ComponentConstructor = new (props: Record<string, unknown>) => JSX.ElementClass;
+declare global {
+    namespace JSX {
+        interface Element {
+            $$typeof: symbol;
+            children: ElementChildren;
+            props: Record<string, unknown> | null;
+            type: ComponentConstructor | string;
+        }
+        interface ElementAttributesProperty {
+            props: Record<string, unknown> | null;
+        }
+        interface ElementClass {
+            render: () => JSX.Element | null;
+        }
+        interface ElementChildrenAttribute {
+            children: ElementChildren;
+        }
+        interface IntrinsicElements {
+            ansi: {
+                children?: never;
+                escapes: Color | Array<Color>;
+            };
+            newline: {
+                children?: never;
+            };
+            text: {
+                children: ElementChildren;
+                indent?: number | undefined;
+            };
+        }
+    }
+}
+/**
+ * Options to configure an instance of the {@link Scribbler}.
+ */
+interface ScribblerOptions {
+    /**
+     * Do not include ANSI color escape codes in the output. Default: `false`.
+     */
+    noColors?: boolean;
+}
+/**
+ * Provides the JSX factory function and renderer.
+ */
+declare class Scribbler {
+    #private;
+    /**
+     * @param options - {@link ScribblerOptions | Options} to configure an instance of the Scribbler.
+     */
+    constructor(options?: ScribblerOptions);
+    /**
+     * Creates a new text element of the given `type`.
+     */
+    static createElement(type: ComponentConstructor | string, props: Record<string, unknown> | null, ...children: Array<ElementChildren>): JSX.Element;
+    /**
+     * Renders the provided JSX `element` and returns the resulting string.
+     */
+    render(element: JSX.Element | null): string;
+}
+
+export { Assertion, AssertionSource, Checker, Cli, CollectService, Color, type CommandLineOptions, type ConfigFileOptions, ConfigService, DescribeResult, Diagnostic, DiagnosticCategory, type DiagnosticOrigin, Environment, type Event, EventEmitter, type EventHandler, ExpectResult, FileResult, type FileResultStatus, type ItemDefinition, Line, Logger, type LoggerOptions, OptionBrand, type OptionDefinition, OptionDefinitionsMap, OptionGroup, ProjectResult, ProjectService, Reporter, type ResolvedConfig, Result, ResultCount, ResultManager, ResultStatus, ResultTiming, Scribbler, type ScribblerOptions, StoreService, SummaryReporter, TSTyche, TargetResult, TaskRunner, TestMember, TestMemberBrand, TestMemberFlags, TestResult, TestTree, Text, ThoroughReporter, type TypeChecker, addsPackageStepText, describeNameText, diagnosticText, fileStatusText, fileViewText, summaryText, testNameText, usesCompilerStepText };