tstyche 4.0.0-rc.0 → 4.0.0

package/README.md

@@ -5,7 +5,7 @@
 [![install-size][install-size-badge]][install-size-url]
 [![coverage][coverage-badge]][coverage-url]
 
-The Essential Type Testing Tool.
+Everything You Need for Type Testing.
 
 ---
 
@@ -37,21 +37,29 @@ To organize, debug and plan tests TSTyche has:
 
 ## Assertions
 
-The assertions can be used to write type tests (like in the above example) or mixed in your functional tests:
+The assertions can be used to write type tests (like in the above example) or mixed in your unit tests:
 
 ```ts
 import assert from "node:assert";
 import test from "node:test";
 import * as tstyche from "tstyche";
 
-function secondItem<T>(target: Array<T>): T | undefined {
-  return target[1];
+function toMilliseconds(value: number) {
+  if (typeof value === "number" && !Number.isNaN(value)) {
+    return value * 1000;
+  }
+
+  throw new Error("Not a number");
 }
 
-test("handles numbers", () => {
-  assert.strictEqual(secondItem([1, 2, 3]), 2);
+test("toMilliseconds", () => {
+  const sample = toMilliseconds(10);
+
+  assert.equal(sample, 10_000);
+  tstyche.expect(sample).type.toBe<number>();
 
-  tstyche.expect(secondItem([1, 2, 3])).type.toBe<number | undefined>();
+  // Will pass as a type test and not throw at runtime
+  tstyche.expect(toMilliseconds).type.not.toBeCallableWith("20");
 });
 ```
 

package/build/tstyche.d.ts

@@ -20,60 +20,6 @@ declare class Cli {
     run(commandLine: Array<string>, cancellationToken?: CancellationToken): Promise<void>;
 }
 
-declare enum TestTreeNodeBrand {
-    Describe = "describe",
-    Test = "test",
-    Expect = "expect",
-    When = "when"
-}
-
-declare enum TestTreeNodeFlags {
-    None = 0,
-    Fail = 1,
-    Only = 2,
-    Skip = 4,
-    Todo = 8
-}
-
-declare class WhenNode extends TestTreeNode {
-    actionNode: ts.CallExpression;
-    actionNameNode: ts.PropertyAccessExpression;
-    abilityDiagnostics: Set<ts.Diagnostic> | undefined;
-    target: ts.NodeArray<ts.Expression> | ts.NodeArray<ts.TypeNode>;
-    constructor(compiler: typeof ts, brand: TestTreeNodeBrand, node: ts.CallExpression, parent: TestTree | TestTreeNode, flags: TestTreeNodeFlags, actionNode: ts.CallExpression, actionNameNode: ts.PropertyAccessExpression);
-}
-
-declare class TestTreeNode {
-    brand: TestTreeNodeBrand;
-    children: Array<TestTreeNode | AssertionNode | WhenNode>;
-    diagnostics: Set<ts.Diagnostic>;
-    flags: TestTreeNodeFlags;
-    name: string;
-    node: ts.CallExpression;
-    parent: TestTree | TestTreeNode;
-    constructor(compiler: typeof ts, brand: TestTreeNodeBrand, node: ts.CallExpression, parent: TestTree | TestTreeNode, flags: TestTreeNodeFlags);
-}
-
-declare class TestTree {
-    children: Array<TestTreeNode | AssertionNode | WhenNode>;
-    diagnostics: Set<ts.Diagnostic>;
-    hasOnly: boolean;
-    sourceFile: ts.SourceFile;
-    constructor(diagnostics: Set<ts.Diagnostic>, sourceFile: ts.SourceFile);
-}
-
-declare class AssertionNode extends TestTreeNode {
-    abilityDiagnostics: Set<ts.Diagnostic> | undefined;
-    isNot: boolean;
-    matcherNode: ts.CallExpression | ts.Decorator;
-    matcherNameNode: ts.PropertyAccessExpression;
-    modifierNode: ts.PropertyAccessExpression;
-    notNode: ts.PropertyAccessExpression | undefined;
-    source: ts.NodeArray<ts.Expression> | ts.NodeArray<ts.TypeNode>;
-    target: ts.NodeArray<ts.Expression> | ts.NodeArray<ts.TypeNode> | undefined;
-    constructor(compiler: typeof ts, brand: TestTreeNodeBrand, node: ts.CallExpression, parent: TestTree | TestTreeNode, flags: TestTreeNodeFlags, matcherNode: ts.CallExpression | ts.Decorator, matcherNameNode: ts.PropertyAccessExpression, modifierNode: ts.PropertyAccessExpression, notNode?: ts.PropertyAccessExpression);
-}
-
 declare enum OptionBrand {
     String = "string",
     Number = "number",
@@ -94,58 +40,13 @@ declare class ConfigDiagnosticText {
     static requiresValueType(optionName: string, optionBrand: OptionBrand): string;
     static seen(element: string): string;
     static testFileMatchCannotStartWith(segment: string): Array<string>;
+    static unexpected(element: string): string;
     static unknownOption(optionName: string): string;
     static usage(optionName: string, optionBrand: OptionBrand): Array<string>;
     static versionIsNotSupported(value: string): string;
     static watchCannotBeEnabled(): string;
 }
 
-/**
- * Options loaded from the configuration file.
- */
-interface ConfigFileOptions {
-    /**
-     * Enable type error reporting for source files.
-     */
-    checkSourceFiles?: boolean;
-    /**
-     * Stop running tests after the first failed assertion.
-     */
-    failFast?: boolean;
-    /**
-     * The list of plugins to use.
-     */
-    plugins?: Array<string>;
-    /**
-     * Reject the 'any' type passed as an argument to the 'expect()' function or a matcher.
-     */
-    rejectAnyType?: boolean;
-    /**
-     * Reject the 'never' type passed as an argument to the 'expect()' function or a matcher.
-     */
-    rejectNeverType?: boolean;
-    /**
-     * The list of reporters to use.
-     */
-    reporters?: Array<string>;
-    /**
-     * 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>;
-    /**
-     * The look up strategy to be used to find the TSConfig file.
-     */
-    tsconfig?: string;
-}
-
 /**
  * Options passed through the command line.
  */
@@ -220,6 +121,58 @@ interface CommandLineOptions {
     watch?: boolean;
 }
 
+/**
+ * Options loaded from the configuration file.
+ */
+interface ConfigFileOptions {
+    /**
+     * Enable type error reporting for source files.
+     */
+    checkSourceFiles?: boolean;
+    /**
+     * Stop running tests after the first failed assertion.
+     */
+    failFast?: boolean;
+    /**
+     * The list of plugins to use.
+     */
+    plugins?: Array<string>;
+    /**
+     * Reject the 'any' type passed as an argument to the 'expect()' function or a matcher.
+     */
+    rejectAnyType?: boolean;
+    /**
+     * Reject the 'never' type passed as an argument to the 'expect()' function or a matcher.
+     */
+    rejectNeverType?: boolean;
+    /**
+     * The list of reporters to use.
+     */
+    reporters?: Array<string>;
+    /**
+     * 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>;
+    /**
+     * The look up strategy to be used to find the TSConfig file.
+     */
+    tsconfig?: string;
+}
+
+interface InlineConfig {
+    if?: {
+        target?: Array<string>;
+    };
+    template?: boolean;
+}
 interface ResolvedConfig extends Omit<CommandLineOptions, "config" | keyof ConfigFileOptions>, Required<ConfigFileOptions> {
     /**
      * The path to a TSTyche configuration file.
@@ -230,6 +183,7 @@ interface ResolvedConfig extends Omit<CommandLineOptions, "config" | keyof Confi
      */
     pathMatch: Array<string>;
 }
+
 declare class Config {
     #private;
     static parseCommandLine(commandLine: Array<string>): Promise<{
@@ -249,6 +203,25 @@ declare class Config {
     static resolveConfigFilePath(filePath?: string): string;
 }
 
+interface TextRange {
+    start: number;
+    end: number;
+    text: string;
+}
+interface DirectiveRange {
+    namespace: TextRange;
+    directive?: TextRange;
+    argument?: TextRange;
+}
+type DirectiveRanges = Array<DirectiveRange> & {
+    sourceFile: ts.SourceFile;
+};
+declare class Directive {
+    #private;
+    static getDirectiveRanges(compiler: typeof ts, sourceFile: ts.SourceFile, position?: number): DirectiveRanges | undefined;
+    static getInlineConfig(ranges: DirectiveRanges | undefined): Promise<InlineConfig | undefined>;
+}
+
 declare enum DiagnosticCategory {
     Error = "error",
     Warning = "warning"
@@ -304,6 +277,7 @@ type DiagnosticsHandler<T extends Diagnostic | Array<Diagnostic> = Diagnostic> =
 declare enum OptionGroup {
     CommandLine = 2,
     ConfigFile = 4,
+    InlineConditions = 8,
     ResolvedConfig = 6
 }
 
@@ -334,6 +308,62 @@ declare class Options {
 
 declare const defaultOptions: Required<ConfigFileOptions>;
 
+declare enum TestTreeNodeBrand {
+    Describe = "describe",
+    Test = "test",
+    Expect = "expect",
+    When = "when"
+}
+
+declare enum TestTreeNodeFlags {
+    None = 0,
+    Fail = 1,
+    Only = 2,
+    Skip = 4,
+    Todo = 8
+}
+
+declare class WhenNode extends TestTreeNode {
+    actionNode: ts.CallExpression;
+    actionNameNode: ts.PropertyAccessExpression;
+    abilityDiagnostics: Set<ts.Diagnostic> | undefined;
+    target: ts.NodeArray<ts.Expression> | ts.NodeArray<ts.TypeNode>;
+    constructor(compiler: typeof ts, brand: TestTreeNodeBrand, node: ts.CallExpression, parent: TestTree | TestTreeNode, flags: TestTreeNodeFlags, actionNode: ts.CallExpression, actionNameNode: ts.PropertyAccessExpression);
+}
+
+declare class TestTreeNode {
+    brand: TestTreeNodeBrand;
+    children: Array<TestTreeNode | AssertionNode | WhenNode>;
+    diagnostics: Set<ts.Diagnostic>;
+    flags: TestTreeNodeFlags;
+    name: string;
+    node: ts.CallExpression;
+    parent: TestTree | TestTreeNode;
+    constructor(compiler: typeof ts, brand: TestTreeNodeBrand, node: ts.CallExpression, parent: TestTree | TestTreeNode, flags: TestTreeNodeFlags);
+    getDirectiveRanges(compiler: typeof ts): DirectiveRanges | undefined;
+}
+
+declare class TestTree {
+    children: Array<TestTreeNode | AssertionNode | WhenNode>;
+    diagnostics: Set<ts.Diagnostic>;
+    hasOnly: boolean;
+    sourceFile: ts.SourceFile;
+    constructor(diagnostics: Set<ts.Diagnostic>, sourceFile: ts.SourceFile);
+    getDirectiveRanges(compiler: typeof ts): DirectiveRanges | undefined;
+}
+
+declare class AssertionNode extends TestTreeNode {
+    abilityDiagnostics: Set<ts.Diagnostic> | undefined;
+    isNot: boolean;
+    matcherNode: ts.CallExpression | ts.Decorator;
+    matcherNameNode: ts.PropertyAccessExpression;
+    modifierNode: ts.PropertyAccessExpression;
+    notNode: ts.PropertyAccessExpression | undefined;
+    source: ts.NodeArray<ts.Expression> | ts.NodeArray<ts.TypeNode>;
+    target: ts.NodeArray<ts.Expression> | ts.NodeArray<ts.TypeNode> | undefined;
+    constructor(compiler: typeof ts, brand: TestTreeNodeBrand, node: ts.CallExpression, parent: TestTree | TestTreeNode, flags: TestTreeNodeFlags, matcherNode: ts.CallExpression | ts.Decorator, matcherNameNode: ts.PropertyAccessExpression, modifierNode: ts.PropertyAccessExpression, notNode: ts.PropertyAccessExpression | undefined);
+}
+
 declare class ProjectService {
     #private;
     constructor(compiler: typeof ts, resolvedConfig: ResolvedConfig);
@@ -546,6 +576,8 @@ type Event = ["config:error", {
     result: TaskResult;
 }] | ["task:end", {
     result: TaskResult;
+}] | ["directive:error", {
+    diagnostics: Array<Diagnostic>;
 }] | ["collect:start", {
     tree: TestTree;
 }] | ["collect:error", {
@@ -855,6 +887,7 @@ declare class Store {
 declare class Version {
     #private;
     static isGreaterThan(source: string, target: string): boolean;
+    static isIncluded(source: string, range: Array<string>): boolean;
     static isSatisfiedWith(source: string, target: string): boolean;
 }
 
@@ -886,5 +919,5 @@ declare class WhenService {
     action(when: WhenNode): void;
 }
 
-export { AssertionNode, BaseReporter, CancellationHandler, CancellationReason, CancellationToken, Cli, CollectService, Color, Config, ConfigDiagnosticText, DescribeResult, Diagnostic, DiagnosticCategory, DiagnosticOrigin, EventEmitter, ExitCodeHandler, ExpectResult, ExpectService, FileWatcher, InputService, Line, ListReporter, OptionBrand, OptionGroup, Options, OutputService, Path, PluginService, ProjectResult, ProjectService, Reject, Result, ResultCount, ResultHandler, ResultStatus, ResultTiming, Runner, Scribbler, ScribblerJsx, Select, SelectDiagnosticText, SetupReporter, SourceFile, Store, SummaryReporter, TargetResult, Task, TaskResult, TestResult, TestTree, TestTreeNode, TestTreeNodeBrand, TestTreeNodeFlags, Text, Version, WatchReporter, WatchService, Watcher, WhenNode, WhenService, addsPackageText, argumentIsProvided, argumentOrTypeArgumentIsProvided, defaultOptions, describeNameText, diagnosticBelongsToNode, diagnosticText, environmentOptions, fileViewText, formattedText, getDiagnosticMessageText, getTextSpanEnd, helpText, isDiagnosticWithLocation, nodeBelongsToArgumentList, summaryText, taskStatusText, testNameText, usesCompilerText, waitingForFileChangesText, watchUsageText };
-export type { CodeFrameOptions, CommandLineOptions, ConfigFileOptions, DiagnosticsHandler, EnvironmentOptions, Event, EventHandler, FileWatchHandler, InputHandler, ItemDefinition, MatchResult, OptionDefinition, Plugin, Reporter, ReporterEvent, ResolvedConfig, ScribblerOptions, SelectHookContext, TargetResultStatus, TaskResultStatus, TypeChecker, WatchHandler, WatcherOptions };
+export { AssertionNode, BaseReporter, CancellationHandler, CancellationReason, CancellationToken, Cli, CollectService, Color, Config, ConfigDiagnosticText, DescribeResult, Diagnostic, DiagnosticCategory, DiagnosticOrigin, Directive, EventEmitter, ExitCodeHandler, ExpectResult, ExpectService, FileWatcher, InputService, Line, ListReporter, OptionBrand, OptionGroup, Options, OutputService, Path, PluginService, ProjectResult, ProjectService, Reject, Result, ResultCount, ResultHandler, ResultStatus, ResultTiming, Runner, Scribbler, ScribblerJsx, Select, SelectDiagnosticText, SetupReporter, SourceFile, Store, SummaryReporter, TargetResult, Task, TaskResult, TestResult, TestTree, TestTreeNode, TestTreeNodeBrand, TestTreeNodeFlags, Text, Version, WatchReporter, WatchService, Watcher, WhenNode, WhenService, addsPackageText, argumentIsProvided, argumentOrTypeArgumentIsProvided, defaultOptions, describeNameText, diagnosticBelongsToNode, diagnosticText, environmentOptions, fileViewText, formattedText, getDiagnosticMessageText, getTextSpanEnd, helpText, isDiagnosticWithLocation, nodeBelongsToArgumentList, summaryText, taskStatusText, testNameText, usesCompilerText, waitingForFileChangesText, watchUsageText };
+export type { CodeFrameOptions, CommandLineOptions, ConfigFileOptions, DiagnosticsHandler, DirectiveRange, DirectiveRanges, EnvironmentOptions, Event, EventHandler, FileWatchHandler, InlineConfig, InputHandler, ItemDefinition, MatchResult, OptionDefinition, Plugin, Reporter, ReporterEvent, ResolvedConfig, ScribblerOptions, SelectHookContext, TargetResultStatus, TaskResultStatus, TypeChecker, WatchHandler, WatcherOptions };

package/build/tstyche.js

@@ -49,6 +49,9 @@ class ConfigDiagnosticText {
             "The test files are only collected within the 'rootPath' directory.",
         ];
     }
+    static unexpected(element) {
+        return `Unexpected ${element}.`;
+    }
     static unknownOption(optionName) {
         return `Unknown option '${optionName}'.`;
     }
@@ -292,6 +295,7 @@ var OptionGroup;
 (function (OptionGroup) {
     OptionGroup[OptionGroup["CommandLine"] = 2] = "CommandLine";
     OptionGroup[OptionGroup["ConfigFile"] = 4] = "ConfigFile";
+    OptionGroup[OptionGroup["InlineConditions"] = 8] = "InlineConditions";
     OptionGroup[OptionGroup["ResolvedConfig"] = 6] = "ResolvedConfig";
 })(OptionGroup || (OptionGroup = {}));
 
@@ -376,6 +380,9 @@ class Version {
     static isGreaterThan(source, target) {
         return !(source === target) && Version.#satisfies(source, target);
     }
+    static isIncluded(source, range) {
+        return range.some((target) => source.startsWith(target));
+    }
     static isSatisfiedWith(source, target) {
         return source === target || Version.#satisfies(source, target);
     }
@@ -1004,7 +1011,7 @@ class Options {
         {
             brand: OptionBrand.List,
             description: "The list of TypeScript versions to be tested on.",
-            group: OptionGroup.CommandLine | OptionGroup.ConfigFile,
+            group: OptionGroup.CommandLine | OptionGroup.ConfigFile | OptionGroup.InlineConditions,
             items: {
                 brand: OptionBrand.String,
                 name: "target",
@@ -1239,146 +1246,18 @@ class CommandLineParser {
     }
 }
 
-class JsonNode {
-    origin;
-    text;
-    constructor(text, origin) {
-        this.origin = origin;
-        this.text = text;
-    }
-    getValue(options) {
-        if (this.text == null) {
-            return undefined;
-        }
-        if (/^['"]/.test(this.text)) {
-            return this.text.slice(1, -1);
-        }
-        if (options?.expectsIdentifier) {
-            return this.text;
-        }
-        if (this.text === "true") {
-            return true;
-        }
-        if (this.text === "false") {
-            return false;
-        }
-        if (/^\d/.test(this.text)) {
-            return Number.parseFloat(this.text);
-        }
-        return undefined;
-    }
-}
-
-class JsonScanner {
-    #currentPosition = 0;
-    #previousPosition = 0;
-    #sourceFile;
-    constructor(sourceFile) {
-        this.#sourceFile = sourceFile;
-    }
-    #getOrigin() {
-        return new DiagnosticOrigin(this.#previousPosition, this.#currentPosition, this.#sourceFile);
-    }
-    isRead() {
-        return !(this.#currentPosition < this.#sourceFile.text.length);
-    }
-    #peekCharacter() {
-        return this.#sourceFile.text.charAt(this.#currentPosition);
-    }
-    #peekNextCharacter() {
-        return this.#sourceFile.text.charAt(this.#currentPosition + 1);
-    }
-    peekToken(token) {
-        this.#skipTrivia();
-        return this.#peekCharacter() === token;
-    }
-    read() {
-        this.#skipTrivia();
-        this.#previousPosition = this.#currentPosition;
-        if (/[\s,:\]}]/.test(this.#peekCharacter())) {
-            return new JsonNode(undefined, this.#getOrigin());
-        }
-        let text = "";
-        let closingTokenText = "";
-        if (/[[{'"]/.test(this.#peekCharacter())) {
-            text += this.#readCharacter();
-            switch (text) {
-                case "[":
-                    closingTokenText = "]";
-                    break;
-                case "{":
-                    closingTokenText = "}";
-                    break;
-                default:
-                    closingTokenText = text;
-            }
-        }
-        while (!this.isRead()) {
-            text += this.#readCharacter();
-            if (text.slice(-1) === closingTokenText || (!closingTokenText && /[\s,:\]}]/.test(this.#peekCharacter()))) {
-                break;
-            }
-        }
-        return new JsonNode(text, this.#getOrigin());
-    }
-    #readCharacter() {
-        return this.#sourceFile.text.charAt(this.#currentPosition++);
-    }
-    readToken(token) {
-        this.#skipTrivia();
-        this.#previousPosition = this.#currentPosition;
-        if (this.#peekCharacter() === token) {
-            this.#currentPosition++;
-            return new JsonNode(token, this.#getOrigin());
-        }
-        return new JsonNode(undefined, this.#getOrigin());
-    }
-    #skipTrivia() {
-        while (!this.isRead()) {
-            if (/\s/.test(this.#peekCharacter())) {
-                this.#currentPosition++;
-                continue;
-            }
-            if (this.#peekCharacter() === "/") {
-                if (this.#peekNextCharacter() === "/") {
-                    this.#currentPosition += 2;
-                    while (!this.isRead()) {
-                        if (this.#readCharacter() === "\n") {
-                            break;
-                        }
-                    }
-                    continue;
-                }
-                if (this.#peekNextCharacter() === "*") {
-                    this.#currentPosition += 2;
-                    while (!this.isRead()) {
-                        if (this.#peekCharacter() === "*" && this.#peekNextCharacter() === "/") {
-                            this.#currentPosition += 2;
-                            break;
-                        }
-                        this.#currentPosition++;
-                    }
-                    continue;
-                }
-            }
-            break;
-        }
-        this.#previousPosition = this.#currentPosition;
-    }
-}
-
-class ConfigFileParser {
+class ConfigParser {
     #configFileOptions;
     #jsonScanner;
     #onDiagnostics;
     #options;
     #sourceFile;
-    constructor(configFileOptions, sourceFile, onDiagnostics) {
-        this.#configFileOptions = configFileOptions;
-        this.#sourceFile = sourceFile;
+    constructor(configOptions, optionGroup, sourceFile, jsonScanner, onDiagnostics) {
+        this.#configFileOptions = configOptions;
+        this.#jsonScanner = jsonScanner;
         this.#onDiagnostics = onDiagnostics;
-        this.#options = Options.for(OptionGroup.ConfigFile);
-        this.#jsonScanner = new JsonScanner(this.#sourceFile);
+        this.#sourceFile = sourceFile;
+        this.#options = Options.for(optionGroup);
     }
     #onRequiresValue(optionDefinition, jsonNode, isListItem) {
         const text = isListItem
@@ -1471,9 +1350,8 @@ class ConfigFileParser {
             if (!optionDefinition) {
                 const text = ConfigDiagnosticText.unknownOption(optionName);
                 this.#onDiagnostics(Diagnostic.error(text, optionNameNode.origin));
-                if (this.#jsonScanner.readToken(":")) {
-                    this.#jsonScanner.read();
-                }
+                this.#jsonScanner.readToken(":");
+                this.#jsonScanner.read();
                 const commaToken = this.#jsonScanner.readToken(",");
                 if (!commaToken.text) {
                     break;
@@ -1500,6 +1378,13 @@ class ConfigFileParser {
                 related: [Diagnostic.error(relatedText, leftBraceToken.origin)],
             });
             this.#onDiagnostics(diagnostic);
+            return;
+        }
+        const unexpectedToken = this.#jsonScanner.readToken(/\S/);
+        if (unexpectedToken.text != null) {
+            const text = ConfigDiagnosticText.unexpected("token");
+            const diagnostic = Diagnostic.error(text, unexpectedToken.origin);
+            this.#onDiagnostics(diagnostic);
         }
     }
     async parse() {
@@ -1507,6 +1392,139 @@ class ConfigFileParser {
     }
 }
 
+class JsonNode {
+    origin;
+    text;
+    constructor(text, origin) {
+        this.origin = origin;
+        this.text = text;
+    }
+    getValue(options) {
+        if (this.text == null) {
+            return undefined;
+        }
+        if (/^['"]/.test(this.text)) {
+            return this.text.slice(1, -1);
+        }
+        if (options?.expectsIdentifier) {
+            return this.text;
+        }
+        if (this.text === "true") {
+            return true;
+        }
+        if (this.text === "false") {
+            return false;
+        }
+        if (/^\d/.test(this.text)) {
+            return Number.parseFloat(this.text);
+        }
+        return undefined;
+    }
+}
+
+class JsonScanner {
+    #end;
+    #position;
+    #previousPosition;
+    #sourceFile;
+    constructor(sourceFile, options) {
+        this.#end = options?.end ?? sourceFile.text.length;
+        this.#position = options?.start ?? 0;
+        this.#previousPosition = options?.start ?? 0;
+        this.#sourceFile = sourceFile;
+    }
+    #getOrigin() {
+        return new DiagnosticOrigin(this.#previousPosition, this.#position, this.#sourceFile);
+    }
+    isRead() {
+        return !(this.#position < this.#end);
+    }
+    #peekCharacter() {
+        return this.#sourceFile.text.charAt(this.#position);
+    }
+    #peekNextCharacter() {
+        return this.#sourceFile.text.charAt(this.#position + 1);
+    }
+    peekToken(token) {
+        this.#skipTrivia();
+        return this.#peekCharacter() === token;
+    }
+    read() {
+        this.#skipTrivia();
+        this.#previousPosition = this.#position;
+        if (/[\s,:\]}]/.test(this.#peekCharacter())) {
+            return new JsonNode(undefined, this.#getOrigin());
+        }
+        let text = "";
+        let closingTokenText = "";
+        if (/[[{'"]/.test(this.#peekCharacter())) {
+            text += this.#readCharacter();
+            switch (text) {
+                case "[":
+                    closingTokenText = "]";
+                    break;
+                case "{":
+                    closingTokenText = "}";
+                    break;
+                default:
+                    closingTokenText = text;
+            }
+        }
+        while (!this.isRead()) {
+            text += this.#readCharacter();
+            if (text.slice(-1) === closingTokenText || (!closingTokenText && /[\s,:\]}]/.test(this.#peekCharacter()))) {
+                break;
+            }
+        }
+        return new JsonNode(text, this.#getOrigin());
+    }
+    #readCharacter() {
+        return this.#sourceFile.text.charAt(this.#position++);
+    }
+    readToken(token) {
+        this.#skipTrivia();
+        this.#previousPosition = this.#position;
+        const character = this.#peekCharacter();
+        if (typeof token === "string" ? token === character : token.test(character)) {
+            this.#position++;
+            return new JsonNode(character, this.#getOrigin());
+        }
+        return new JsonNode(undefined, this.#getOrigin());
+    }
+    #skipTrivia() {
+        while (!this.isRead()) {
+            if (/\s/.test(this.#peekCharacter())) {
+                this.#position++;
+                continue;
+            }
+            if (this.#peekCharacter() === "/") {
+                if (this.#peekNextCharacter() === "/") {
+                    this.#position += 2;
+                    while (!this.isRead()) {
+                        if (this.#readCharacter() === "\n") {
+                            break;
+                        }
+                    }
+                    continue;
+                }
+                if (this.#peekNextCharacter() === "*") {
+                    this.#position += 2;
+                    while (!this.isRead()) {
+                        if (this.#peekCharacter() === "*" && this.#peekNextCharacter() === "/") {
+                            this.#position += 2;
+                            break;
+                        }
+                        this.#position++;
+                    }
+                    continue;
+                }
+            }
+            break;
+        }
+        this.#previousPosition = this.#position;
+    }
+}
+
 const defaultOptions = {
     checkSourceFiles: true,
     failFast: false,
@@ -1544,7 +1562,7 @@ class Config {
                 encoding: "utf8",
             });
             const sourceFile = new SourceFile(configFilePath, configFileText);
-            const configFileParser = new ConfigFileParser(configFileOptions, sourceFile, Config.#onDiagnostics);
+            const configFileParser = new ConfigParser(configFileOptions, OptionGroup.ConfigFile, sourceFile, new JsonScanner(sourceFile), Config.#onDiagnostics);
             await configFileParser.parse();
             if (configFileOptions.target != null) {
                 configFileOptions.target = await Target.expand(configFileOptions.target);
@@ -1570,6 +1588,114 @@ class Config {
     }
 }
 
+class DirectiveDiagnosticText {
+    static doesNotTakeArgument(directiveName) {
+        return `Directive '${directiveName}' does not take an argument.`;
+    }
+    static isNotSupported(directive) {
+        return `The '${directive}' directive is not supported.`;
+    }
+    static requiresArgument(directiveName) {
+        return `Directive '${directiveName}' requires an argument.`;
+    }
+}
+
+class Directive {
+    static #commentSeparatorRegex = /--+/;
+    static #directiveRegex = /^(\/\/\s*@tstyche)(\s*|-)?(\S*)?(\s*)?(.*)?/i;
+    static getDirectiveRanges(compiler, sourceFile, position = 0) {
+        const comments = compiler.getLeadingCommentRanges(sourceFile.text, position);
+        if (!comments || comments.length === 0) {
+            return;
+        }
+        const ranges = Object.assign([], { sourceFile });
+        for (const comment of comments) {
+            if (comment.kind !== compiler.SyntaxKind.SingleLineCommentTrivia) {
+                continue;
+            }
+            const range = Directive.#getRange(sourceFile, comment);
+            if (range != null) {
+                ranges.push(range);
+            }
+        }
+        return ranges;
+    }
+    static async getInlineConfig(ranges) {
+        if (!ranges) {
+            return;
+        }
+        const inlineConfig = {};
+        for (const range of ranges) {
+            await Directive.#parse(inlineConfig, ranges.sourceFile, range);
+        }
+        return inlineConfig;
+    }
+    static #getRange(sourceFile, comment) {
+        const [text] = sourceFile.text.substring(comment.pos, comment.end).split(Directive.#commentSeparatorRegex);
+        const found = text?.match(Directive.#directiveRegex);
+        const namespaceText = found?.[1];
+        if (!namespaceText) {
+            return;
+        }
+        const ranges = {
+            namespace: { start: comment.pos, end: comment.pos + namespaceText.length, text: namespaceText },
+        };
+        const directiveSeparatorText = found?.[2];
+        const directiveText = found?.[3];
+        if (directiveText != null && directiveText.length > 0) {
+            const start = ranges.namespace.end + (directiveSeparatorText?.length ?? 0);
+            ranges.directive = { start, end: start + directiveText.length, text: directiveText };
+        }
+        const argumentSeparatorText = found?.[4];
+        const argumentText = found?.[5]?.trimEnd();
+        if (ranges.directive != null && argumentText != null && argumentText.length > 0) {
+            const start = ranges.directive.end + (argumentSeparatorText?.length ?? 0);
+            ranges.argument = { start, end: start + argumentText.length, text: argumentText };
+        }
+        return ranges;
+    }
+    static #onDiagnostics(diagnostic) {
+        EventEmitter.dispatch(["directive:error", { diagnostics: [diagnostic] }]);
+    }
+    static async #parse(inlineConfig, sourceFile, ranges) {
+        switch (ranges.directive?.text) {
+            case "if":
+                {
+                    if (!ranges.argument?.text) {
+                        const text = DirectiveDiagnosticText.requiresArgument(ranges.directive.text);
+                        const origin = new DiagnosticOrigin(ranges.directive.start, ranges.directive.end, sourceFile);
+                        Directive.#onDiagnostics(Diagnostic.error(text, origin));
+                        return;
+                    }
+                    const value = await Directive.#parseJson(sourceFile, ranges.argument.start, ranges.argument.end);
+                    inlineConfig.if = value;
+                }
+                return;
+            case "template":
+                if (ranges.argument?.text != null) {
+                    const text = DirectiveDiagnosticText.doesNotTakeArgument(ranges.directive.text);
+                    const origin = new DiagnosticOrigin(ranges.directive.start, ranges.directive.end, sourceFile);
+                    Directive.#onDiagnostics(Diagnostic.error(text, origin));
+                }
+                inlineConfig.template = true;
+                return;
+        }
+        const target = ranges?.directive ?? ranges.namespace;
+        const text = DirectiveDiagnosticText.isNotSupported(target.text);
+        const origin = new DiagnosticOrigin(target.start, target.end, sourceFile);
+        Directive.#onDiagnostics(Diagnostic.error(text, origin));
+    }
+    static async #parseJson(sourceFile, start, end) {
+        const inlineOptions = {};
+        const configParser = new ConfigParser(inlineOptions, OptionGroup.InlineConditions, sourceFile, new JsonScanner(sourceFile, { start, end }), Directive.#onDiagnostics);
+        await configParser.parse();
+        if ("target" in inlineOptions) {
+            inlineOptions["target"] = await Target.expand(inlineOptions["target"]);
+        }
+        return inlineOptions;
+    }
+}
+
 class CancellationHandler {
     #cancellationToken;
     #cancellationReason;
@@ -1777,6 +1903,7 @@ class ResultHandler {
                 this.#taskResult.timing.start = Date.now();
                 break;
             case "task:error":
+            case "directive:error":
             case "collect:error":
                 this.#targetResult.status = ResultStatus.Failed;
                 this.#taskResult.status = ResultStatus.Failed;
@@ -2380,6 +2507,7 @@ class ListReporter extends BaseReporter {
                 this.#hasReportedError = false;
                 break;
             case "task:error":
+            case "directive:error":
             case "collect:error":
                 for (const diagnostic of payload.diagnostics) {
                     this.#fileView.addMessage(diagnosticText(diagnostic));
@@ -2895,6 +3023,9 @@ class TestTreeNode {
             }
         }
     }
+    getDirectiveRanges(compiler) {
+        return Directive.getDirectiveRanges(compiler, this.node.getSourceFile(), this.node.getFullStart());
+    }
 }
 
 class AssertionNode extends TestTreeNode {
@@ -2917,7 +3048,8 @@ class AssertionNode extends TestTreeNode {
             this.target = this.matcherNode.typeArguments ?? this.matcherNode.arguments;
         }
         for (const diagnostic of parent.diagnostics) {
-            if (diagnosticBelongsToNode(diagnostic, this.source)) {
+            if (diagnosticBelongsToNode(diagnostic, this.source) ||
+                (this.target != null && diagnosticBelongsToNode(diagnostic, this.target))) {
                 this.diagnostics.add(diagnostic);
                 parent.diagnostics.delete(diagnostic);
             }
@@ -3185,6 +3317,9 @@ class TestTree {
         this.diagnostics = diagnostics;
         this.sourceFile = sourceFile;
     }
+    getDirectiveRanges(compiler) {
+        return Directive.getDirectiveRanges(compiler, this.sourceFile);
+    }
 }
 
 class WhenNode extends TestTreeNode {
@@ -4529,6 +4664,7 @@ class WhenService {
 
 class TestTreeWalker {
     #cancellationToken;
+    #compiler;
     #expectService;
     #hasOnly;
     #onTaskDiagnostics;
@@ -4536,6 +4672,7 @@ class TestTreeWalker {
     #resolvedConfig;
     #whenService;
     constructor(compiler, typeChecker, resolvedConfig, onTaskDiagnostics, options) {
+        this.#compiler = compiler;
         this.#resolvedConfig = resolvedConfig;
         this.#onTaskDiagnostics = onTaskDiagnostics;
         this.#cancellationToken = options.cancellationToken;
@@ -4545,43 +4682,46 @@ class TestTreeWalker {
         this.#expectService = new ExpectService(compiler, typeChecker, reject);
         this.#whenService = new WhenService(reject, onTaskDiagnostics);
     }
-    #resolveRunMode(mode, testNode) {
-        if (testNode.flags & TestTreeNodeFlags.Fail) {
+    async #resolveRunMode(mode, node) {
+        const directiveRanges = node.getDirectiveRanges(this.#compiler);
+        const inlineConfig = await Directive.getInlineConfig(directiveRanges);
+        if (inlineConfig?.if?.target != null && !Version.isIncluded(this.#compiler.version, inlineConfig.if.target)) {
+            mode |= RunMode.Skip;
+        }
+        if (node.flags & TestTreeNodeFlags.Fail) {
             mode |= RunMode.Fail;
         }
-        if (testNode.flags & TestTreeNodeFlags.Only ||
-            (this.#resolvedConfig.only != null &&
-                testNode.name.toLowerCase().includes(this.#resolvedConfig.only.toLowerCase()))) {
+        if (node.flags & TestTreeNodeFlags.Only ||
+            (this.#resolvedConfig.only != null && node.name.toLowerCase().includes(this.#resolvedConfig.only.toLowerCase()))) {
             mode |= RunMode.Only;
         }
-        if (testNode.flags & TestTreeNodeFlags.Skip ||
-            (this.#resolvedConfig.skip != null &&
-                testNode.name.toLowerCase().includes(this.#resolvedConfig.skip.toLowerCase()))) {
+        if (node.flags & TestTreeNodeFlags.Skip ||
+            (this.#resolvedConfig.skip != null && node.name.toLowerCase().includes(this.#resolvedConfig.skip.toLowerCase()))) {
             mode |= RunMode.Skip;
         }
-        if (testNode.flags & TestTreeNodeFlags.Todo) {
+        if (node.flags & TestTreeNodeFlags.Todo) {
             mode |= RunMode.Todo;
         }
-        if (this.#position != null && testNode.node.getStart() === this.#position) {
+        if (this.#position != null && node.node.getStart() === this.#position) {
             mode |= RunMode.Only;
             mode &= ~RunMode.Skip;
         }
         return mode;
     }
-    visit(nodes, runMode, parentResult) {
+    async visit(nodes, runMode, parentResult) {
         for (const node of nodes) {
             if (this.#cancellationToken?.isCancellationRequested) {
                 break;
             }
             switch (node.brand) {
                 case TestTreeNodeBrand.Describe:
-                    this.#visitDescribe(node, runMode, parentResult);
+                    await this.#visitDescribe(node, runMode, parentResult);
                     break;
                 case TestTreeNodeBrand.Test:
-                    this.#visitTest(node, runMode, parentResult);
+                    await this.#visitTest(node, runMode, parentResult);
                     break;
                 case TestTreeNodeBrand.Expect:
-                    this.#visitAssertion(node, runMode, parentResult);
+                    await this.#visitAssertion(node, runMode, parentResult);
                     break;
                 case TestTreeNodeBrand.When:
                     this.#visitWhen(node);
@@ -4589,11 +4729,11 @@ class TestTreeWalker {
             }
         }
     }
-    #visitAssertion(assertion, runMode, parentResult) {
-        this.visit(assertion.children, runMode, parentResult);
+    async #visitAssertion(assertion, runMode, parentResult) {
+        await this.visit(assertion.children, runMode, parentResult);
         const expectResult = new ExpectResult(assertion, parentResult);
         EventEmitter.dispatch(["expect:start", { result: expectResult }]);
-        runMode = this.#resolveRunMode(runMode, assertion);
+        runMode = await this.#resolveRunMode(runMode, assertion);
         if (runMode & RunMode.Skip || (this.#hasOnly && !(runMode & RunMode.Only))) {
             EventEmitter.dispatch(["expect:skip", { result: expectResult }]);
             return;
@@ -4629,23 +4769,23 @@ class TestTreeWalker {
             EventEmitter.dispatch(["expect:fail", { diagnostics: matchResult.explain(), result: expectResult }]);
         }
     }
-    #visitDescribe(describe, runMode, parentResult) {
+    async #visitDescribe(describe, runMode, parentResult) {
         const describeResult = new DescribeResult(describe, parentResult);
         EventEmitter.dispatch(["describe:start", { result: describeResult }]);
-        runMode = this.#resolveRunMode(runMode, describe);
+        runMode = await this.#resolveRunMode(runMode, describe);
         if (!(runMode & RunMode.Skip || (this.#hasOnly && !(runMode & RunMode.Only)) || runMode & RunMode.Todo) &&
             describe.diagnostics.size > 0) {
             this.#onTaskDiagnostics(Diagnostic.fromDiagnostics([...describe.diagnostics]));
         }
         else {
-            this.visit(describe.children, runMode, describeResult);
+            await this.visit(describe.children, runMode, describeResult);
         }
         EventEmitter.dispatch(["describe:end", { result: describeResult }]);
     }
-    #visitTest(test, runMode, parentResult) {
+    async #visitTest(test, runMode, parentResult) {
         const testResult = new TestResult(test, parentResult);
         EventEmitter.dispatch(["test:start", { result: testResult }]);
-        runMode = this.#resolveRunMode(runMode, test);
+        runMode = await this.#resolveRunMode(runMode, test);
         if (runMode & RunMode.Todo) {
             EventEmitter.dispatch(["test:todo", { result: testResult }]);
             return;
@@ -4660,7 +4800,7 @@ class TestTreeWalker {
             ]);
             return;
         }
-        this.visit(test.children, runMode, testResult);
+        await this.visit(test.children, runMode, testResult);
         if (runMode & RunMode.Skip || (this.#hasOnly && !(runMode & RunMode.Only))) {
             EventEmitter.dispatch(["test:skip", { result: testResult }]);
             return;
@@ -4702,21 +4842,27 @@ class TaskRunner {
         EventEmitter.dispatch(["task:end", { result: taskResult }]);
         this.#projectService.closeFile(task.filePath);
     }
-    async #run(task, taskResult, cancellationToken) {
-        if (!existsSync(task.filePath)) {
-            this.#onDiagnostics([Diagnostic.error(`Test file '${task.filePath}' does not exist.`)], taskResult);
-            return;
-        }
-        let languageService = this.#projectService.getLanguageService(task.filePath);
+    async #resolveTaskFacts(task, taskResult, runMode = RunMode.Normal) {
+        const languageService = this.#projectService.getLanguageService(task.filePath);
         const syntacticDiagnostics = languageService?.getSyntacticDiagnostics(task.filePath);
         if (syntacticDiagnostics != null && syntacticDiagnostics.length > 0) {
             this.#onDiagnostics(Diagnostic.fromDiagnostics(syntacticDiagnostics), taskResult);
             return;
         }
-        let semanticDiagnostics = languageService?.getSemanticDiagnostics(task.filePath);
-        let program = languageService?.getProgram();
-        let sourceFile = program?.getSourceFile(task.filePath);
-        if (sourceFile?.text.startsWith("// @tstyche-template")) {
+        const semanticDiagnostics = languageService?.getSemanticDiagnostics(task.filePath);
+        const program = languageService?.getProgram();
+        const typeChecker = program?.getTypeChecker();
+        const sourceFile = program?.getSourceFile(task.filePath);
+        if (!sourceFile) {
+            return;
+        }
+        const testTree = this.#collectService.createTestTree(sourceFile, semanticDiagnostics);
+        const directiveRanges = testTree.getDirectiveRanges(this.#compiler);
+        const inlineConfig = await Directive.getInlineConfig(directiveRanges);
+        if (inlineConfig?.if?.target != null && !Version.isIncluded(this.#compiler.version, inlineConfig.if.target)) {
+            runMode |= RunMode.Skip;
+        }
+        if (inlineConfig?.template) {
             if (semanticDiagnostics != null && semanticDiagnostics.length > 0) {
                 this.#onDiagnostics(Diagnostic.fromDiagnostics(semanticDiagnostics), taskResult);
                 return;
@@ -4728,41 +4874,39 @@ class TaskRunner {
                 return;
             }
             this.#projectService.openFile(task.filePath, testText, this.#resolvedConfig.rootPath);
-            languageService = this.#projectService.getLanguageService(task.filePath);
-            const syntacticDiagnostics = languageService?.getSyntacticDiagnostics(task.filePath);
-            if (syntacticDiagnostics != null && syntacticDiagnostics.length > 0) {
-                this.#onDiagnostics(Diagnostic.fromDiagnostics(syntacticDiagnostics), taskResult);
-                return;
-            }
-            semanticDiagnostics = languageService?.getSemanticDiagnostics(task.filePath);
-            program = languageService?.getProgram();
-            sourceFile = program?.getSourceFile(task.filePath);
+            return this.#resolveTaskFacts(task, taskResult, runMode);
         }
-        if (!sourceFile) {
+        return { runMode, testTree, typeChecker };
+    }
+    async #run(task, taskResult, cancellationToken) {
+        if (!existsSync(task.filePath)) {
+            this.#onDiagnostics([Diagnostic.error(`Test file '${task.filePath}' does not exist.`)], taskResult);
             return;
         }
-        const testTree = this.#collectService.createTestTree(sourceFile, semanticDiagnostics);
-        if (testTree.diagnostics.size > 0) {
-            this.#onDiagnostics(Diagnostic.fromDiagnostics([...testTree.diagnostics]), taskResult);
+        const facts = await this.#resolveTaskFacts(task, taskResult);
+        if (!facts) {
+            return;
+        }
+        if (facts.testTree.diagnostics.size > 0) {
+            this.#onDiagnostics(Diagnostic.fromDiagnostics([...facts.testTree.diagnostics]), taskResult);
             return;
         }
-        const typeChecker = program?.getTypeChecker();
         const onTaskDiagnostics = (diagnostics) => {
             this.#onDiagnostics(diagnostics, taskResult);
         };
-        const testTreeWalker = new TestTreeWalker(this.#compiler, typeChecker, this.#resolvedConfig, onTaskDiagnostics, {
+        const testTreeWalker = new TestTreeWalker(this.#compiler, facts.typeChecker, this.#resolvedConfig, onTaskDiagnostics, {
             cancellationToken,
-            hasOnly: testTree.hasOnly,
+            hasOnly: facts.testTree.hasOnly,
             position: task.position,
         });
-        testTreeWalker.visit(testTree.children, RunMode.Normal, undefined);
+        await testTreeWalker.visit(facts.testTree.children, facts.runMode, undefined);
     }
 }
 
 class Runner {
     #eventEmitter = new EventEmitter();
     #resolvedConfig;
-    static version = "4.0.0-rc.0";
+    static version = "4.0.0";
     constructor(resolvedConfig) {
         this.#resolvedConfig = resolvedConfig;
     }
@@ -4962,4 +5106,4 @@ class Cli {
     }
 }
 
-export { AssertionNode, BaseReporter, CancellationHandler, CancellationReason, CancellationToken, Cli, CollectService, Color, Config, ConfigDiagnosticText, DescribeResult, Diagnostic, DiagnosticCategory, DiagnosticOrigin, EventEmitter, ExitCodeHandler, ExpectResult, ExpectService, FileWatcher, InputService, Line, ListReporter, OptionBrand, OptionGroup, Options, OutputService, Path, PluginService, ProjectResult, ProjectService, Reject, Result, ResultCount, ResultHandler, ResultStatus, ResultTiming, Runner, Scribbler, Select, SelectDiagnosticText, SetupReporter, SourceFile, Store, SummaryReporter, TargetResult, Task, TaskResult, TestResult, TestTree, TestTreeNode, TestTreeNodeBrand, TestTreeNodeFlags, Text, Version, WatchReporter, WatchService, Watcher, WhenNode, WhenService, addsPackageText, argumentIsProvided, argumentOrTypeArgumentIsProvided, defaultOptions, describeNameText, diagnosticBelongsToNode, diagnosticText, environmentOptions, fileViewText, formattedText, getDiagnosticMessageText, getTextSpanEnd, helpText, isDiagnosticWithLocation, nodeBelongsToArgumentList, summaryText, taskStatusText, testNameText, usesCompilerText, waitingForFileChangesText, watchUsageText };
+export { AssertionNode, BaseReporter, CancellationHandler, CancellationReason, CancellationToken, Cli, CollectService, Color, Config, ConfigDiagnosticText, DescribeResult, Diagnostic, DiagnosticCategory, DiagnosticOrigin, Directive, EventEmitter, ExitCodeHandler, ExpectResult, ExpectService, FileWatcher, InputService, Line, ListReporter, OptionBrand, OptionGroup, Options, OutputService, Path, PluginService, ProjectResult, ProjectService, Reject, Result, ResultCount, ResultHandler, ResultStatus, ResultTiming, Runner, Scribbler, Select, SelectDiagnosticText, SetupReporter, SourceFile, Store, SummaryReporter, TargetResult, Task, TaskResult, TestResult, TestTree, TestTreeNode, TestTreeNodeBrand, TestTreeNodeFlags, Text, Version, WatchReporter, WatchService, Watcher, WhenNode, WhenService, addsPackageText, argumentIsProvided, argumentOrTypeArgumentIsProvided, defaultOptions, describeNameText, diagnosticBelongsToNode, diagnosticText, environmentOptions, fileViewText, formattedText, getDiagnosticMessageText, getTextSpanEnd, helpText, isDiagnosticWithLocation, nodeBelongsToArgumentList, summaryText, taskStatusText, testNameText, usesCompilerText, waitingForFileChangesText, watchUsageText };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tstyche",
-  "version": "4.0.0-rc.0",
-  "description": "The Essential Type Testing Tool.",
+  "version": "4.0.0",
+  "description": "Everything You Need for Type Testing.",
   "keywords": [
     "typescript",
     "types",