@flint.fyi/rule-tester 0.14.0 → 0.14.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @flint/rule-tester
 
+## 0.14.2
+
+### Patch Changes
+
+- a3f9043: fix: respect \`only\` and \`skip\` options in valid RuleTester cases
+- Updated dependencies [3d19082]
+  - @flint.fyi/core@0.15.1
+
+## 0.14.1
+
+### Patch Changes
+
+- b58d145: corrected logic and types for current-file suggestions
+
 ## 0.14.0
 
 ### Minor Changes

package/lib/RuleTester.d.ts

@@ -1,9 +1,11 @@
-import { AnyOptionalSchema, AnyRule, BaseAbout, InferredObject } from "@flint.fyi/core";
+import { AnyOptionalSchema, AnyRule, InferredObject, RuleAbout } from "@flint.fyi/core";
 import { InvalidTestCase, ValidTestCase } from "./types.js";
 export interface RuleTesterOptions {
     describe?: TesterSetupDescribe;
     it?: TesterSetupIt;
+    only?: TesterSetupIt;
     scope?: Record<string, unknown>;
+    skip?: TesterSetupIt;
 }
 export interface TestCases<Options extends object | undefined> {
     invalid: InvalidTestCase<Options>[];
@@ -13,6 +15,6 @@ export type TesterSetupDescribe = (description: string, setup: () => void) => vo
 export type TesterSetupIt = (description: string, setup: () => Promise<void>) => void;
 export declare class RuleTester {
     #private;
-    constructor({ describe, it, scope }?: RuleTesterOptions);
-    describe<OptionsSchema extends AnyOptionalSchema | undefined>(rule: AnyRule<BaseAbout, OptionsSchema>, { invalid, valid }: TestCases<InferredObject<OptionsSchema>>): void;
+    constructor({ describe, it, only, scope, skip, }?: RuleTesterOptions);
+    describe<OptionsSchema extends AnyOptionalSchema | undefined>(rule: AnyRule<RuleAbout, OptionsSchema>, { invalid, valid }: TestCases<InferredObject<OptionsSchema>>): void;
 }

package/lib/RuleTester.js

@@ -7,12 +7,27 @@ import { runTestCaseRule } from "./runTestCaseRule.js";
 export class RuleTester {
     #fileFactories;
     #testerOptions;
-    constructor({ describe, it, scope = globalThis } = {}) {
+    constructor({ describe, it, only, scope = globalThis, skip, } = {}) {
         this.#fileFactories = new CachedFactory((language) => language.prepare());
+        it = defaultTo(it, scope, "it");
+        if (!skip && "skip" in it && typeof it.skip === "function") {
+            skip = it.skip;
+        }
+        if (!only && "only" in it && typeof it.only === "function") {
+            only = it.only;
+        }
+        if (!skip) {
+            throw new TypeError("RuleTester needs a `skip` function");
+        }
+        if (!only) {
+            throw new TypeError("RuleTester needs a `only` function");
+        }
         this.#testerOptions = {
             describe: defaultTo(describe, scope, "describe"),
-            it: defaultTo(it, scope, "it"),
+            it,
+            only,
             scope,
+            skip,
         };
     }
     describe(rule, { invalid, valid }) {
@@ -31,10 +46,10 @@ export class RuleTester {
     }
     #itInvalidCase(rule, testCase) {
         const testCaseNormalized = normalizeTestCase(testCase);
-        this.#testerOptions.it(testCase.code, async () => {
+        this.#itTestCase(testCaseNormalized, async () => {
             const reports = await runTestCaseRule(this.#fileFactories, {
                 // TODO: Figure out a way around the type assertion...
-                options: (testCase.options ?? {}),
+                options: testCase.options ?? {},
                 rule,
             }, testCaseNormalized);
             const actualSnapshot = createReportSnapshot(testCase.code, reports);
@@ -43,10 +58,24 @@ export class RuleTester {
             assert.deepStrictEqual(actualSuggestions, testCase.suggestions);
         });
     }
+    #itTestCase(testCase, setup) {
+        let test = testCase.only
+            ? this.#testerOptions.only
+            : this.#testerOptions.it;
+        if (testCase.skip) {
+            if ("skip" in test && typeof test.skip === "function") {
+                test = test.skip;
+            }
+            else {
+                test = this.#testerOptions.skip;
+            }
+        }
+        test(testCase.code, setup);
+    }
     #itValidCase(rule, testCaseRaw) {
         const testCase = typeof testCaseRaw === "string" ? { code: testCaseRaw } : testCaseRaw;
         const testCaseNormalized = normalizeTestCase(testCase);
-        this.#testerOptions.it(testCase.code, async () => {
+        this.#itTestCase(testCaseNormalized, async () => {
             const reports = await runTestCaseRule(this.#fileFactories, {
                 // TODO: Figure out a way around the type assertion...
                 options: (testCase.options ?? {}),

package/lib/createReportSnapshot.js

@@ -10,7 +10,7 @@ function createReportSnapshotAt(sourceText, report) {
     const range = report.range;
     const lineEndIndex = ifNegative(sourceText.indexOf("\n", range.begin.raw), sourceText.length);
     const lineStartIndex = ifNegative(sourceText.lastIndexOf("\n", range.begin.raw), 0);
-    const column = ifNegative(range.begin.raw - lineStartIndex - 2, 0);
+    const column = ifNegative(range.begin.raw - lineStartIndex - 1, 0);
     const width = range.end.raw - range.begin.raw;
     const injectionPrefix = " ".repeat(column);
     const injectedLines = [

package/lib/predicates.d.ts

@@ -0,0 +1,2 @@
+import { TestSuggestion, TestSuggestionForFiles } from "./types.js";
+export declare function isTestSuggestionForFiles(suggestion: TestSuggestion): suggestion is TestSuggestionForFiles;

package/lib/predicates.js

@@ -0,0 +1,3 @@
+export function isTestSuggestionForFiles(suggestion) {
+    return "files" in suggestion;
+}

package/lib/resolveReportedSuggestions.d.ts

@@ -1,11 +1,14 @@
 import { NormalizedReport } from "@flint.fyi/core";
 import { TestCaseNormalized } from "./normalizeTestCase.js";
 import { InvalidTestCase, TestSuggestionFileCase } from "./types.js";
-export declare function resolveReportedSuggestions(reports: NormalizedReport[], testCaseNormalized: InvalidTestCase & TestCaseNormalized): {
+export declare function resolveReportedSuggestions(reports: NormalizedReport[], testCaseNormalized: InvalidTestCase & TestCaseNormalized): ({
     files: {
         [k: string]: TestSuggestionFileCase[];
-    } | {
-        [testCaseNormalized.fileName]: import("@flint.fyi/core").SuggestionForFile;
-    }[];
+    };
     id: string;
-}[] | undefined;
+    updated?: undefined;
+} | {
+    id: string;
+    updated: string;
+    files?: undefined;
+})[] | undefined;

package/lib/resolveReportedSuggestions.js

@@ -1,5 +1,6 @@
 import { applyChangesToText, isSuggestionForFiles, } from "@flint.fyi/core";
 import { isTruthy } from "@flint.fyi/utils";
+import { isTestSuggestionForFiles } from "./predicates.js";
 export function resolveReportedSuggestions(reports, testCaseNormalized) {
     const suggestionsReported = reports
         .flatMap((report) => report.suggestions)
@@ -7,21 +8,23 @@ export function resolveReportedSuggestions(reports, testCaseNormalized) {
     if (!suggestionsReported.length) {
         return undefined;
     }
-    return suggestionsReported.map((suggestionReported) => ({
-        files: isSuggestionForFiles(suggestionReported)
-            ? resolveReportedSuggestionForFiles(suggestionReported, testCaseNormalized)
-            : [
-                {
-                    [testCaseNormalized.fileName]: suggestionReported,
-                },
-            ],
-        id: suggestionReported.id,
-    }));
+    return suggestionsReported.map((suggestionReported) => isSuggestionForFiles(suggestionReported)
+        ? {
+            files: resolveReportedSuggestionForFiles(suggestionReported, testCaseNormalized),
+            id: suggestionReported.id,
+        }
+        : {
+            id: suggestionReported.id,
+            updated: applyChangesToText([suggestionReported], testCaseNormalized.code),
+        });
 }
 function resolveReportedSuggestionForFiles(suggestionReported, testCaseNormalized) {
     if (!testCaseNormalized.suggestions) {
         return {};
     }
+    if (!testCaseNormalized.suggestions.every(isTestSuggestionForFiles)) {
+        throw new Error("This test case describes suggestions across files, but the rule is only reporting changes to its own file.");
+    }
     return Object.fromEntries(testCaseNormalized.suggestions
         .map((suggestionExpected) => {
         return Object.entries(suggestionExpected.files).map(([filePath, suggestionCasesExpected]) => {

package/lib/resolveReportedSuggestions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/resolveReportedSuggestions.test.js

@@ -0,0 +1,172 @@
+import { describe, expect, it } from "vitest";
+import { resolveReportedSuggestions } from "./resolveReportedSuggestions.js";
+const mockReport = {
+    message: { primary: "", secondary: [], suggestions: [] },
+    range: {
+        begin: { column: 0, line: 1, raw: 0 },
+        end: { column: 3, line: 1, raw: 3 },
+    },
+};
+const mockTestCaseNormalized = {
+    code: "xyz",
+    fileName: "file.ts",
+    snapshot: "",
+};
+describe("resolveReportedSuggestions", () => {
+    it("returns undefined when reports is empty", () => {
+        const result = resolveReportedSuggestions([], mockTestCaseNormalized);
+        expect(result).toEqual(undefined);
+    });
+    it("returns undefined when given one report with no suggestions", () => {
+        const report = {
+            ...mockReport,
+            suggestions: [],
+        };
+        const result = resolveReportedSuggestions([report], mockTestCaseNormalized);
+        expect(result).toEqual(undefined);
+    });
+    it("returns id and updated text when given a single file suggestion", () => {
+        const suggestion = {
+            id: "suggestion",
+            range: { begin: 0, end: 3 },
+            text: "abc",
+        };
+        const report = {
+            ...mockReport,
+            suggestions: [suggestion],
+        };
+        const result = resolveReportedSuggestions([report], mockTestCaseNormalized);
+        expect(result).toEqual([
+            {
+                id: suggestion.id,
+                updated: suggestion.text,
+            },
+        ]);
+    });
+    it("throws when given a test case with no suggestions", () => {
+        const report = {
+            ...mockReport,
+            suggestions: [
+                {
+                    files: {
+                        "file.ts": () => [{ range: { begin: 0, end: 3 }, text: "def" }],
+                    },
+                    id: "suggestion-report",
+                },
+            ],
+        };
+        expect(() => resolveReportedSuggestions([report], {
+            ...mockTestCaseNormalized,
+            suggestions: [
+                {
+                    id: "suggestion-result",
+                    updated: "...",
+                },
+            ],
+        })).toThrowErrorMatchingInlineSnapshot(`[Error: This test case describes suggestions across files, but the rule is only reporting changes to its own file.]`);
+    });
+    it("throws when given a test case that doesn't have cross-file suggestions", () => {
+        const report = {
+            ...mockReport,
+            suggestions: [
+                {
+                    files: {
+                        "file.ts": () => [{ range: { begin: 0, end: 3 }, text: "def" }],
+                    },
+                    id: "suggestion-report",
+                },
+            ],
+        };
+        expect(() => resolveReportedSuggestions([report], {
+            ...mockTestCaseNormalized,
+            suggestions: [
+                {
+                    id: "suggestion-result",
+                    updated: "...",
+                },
+            ],
+        })).toThrowErrorMatchingInlineSnapshot(`[Error: This test case describes suggestions across files, but the rule is only reporting changes to its own file.]`);
+    });
+    it("returns id and a files object when given multi-file suggestions with a single file", () => {
+        const report = {
+            ...mockReport,
+            suggestions: [
+                {
+                    files: {
+                        "file.ts": () => [{ range: { begin: 0, end: 3 }, text: "def" }],
+                    },
+                    id: "suggestion-report",
+                },
+            ],
+        };
+        const result = resolveReportedSuggestions([report], {
+            ...mockTestCaseNormalized,
+            suggestions: [
+                {
+                    files: {
+                        "file.ts": [{ original: "abc", updated: "def" }],
+                    },
+                    id: "suggestion-result",
+                },
+            ],
+        });
+        expect(result).toEqual([
+            {
+                files: {
+                    "file.ts": [
+                        {
+                            original: "abc",
+                            updated: "def",
+                        },
+                    ],
+                },
+                id: "suggestion-report",
+            },
+        ]);
+    });
+    it("returns id and a files object when given multi-file suggestions with multiple file", () => {
+        const report = {
+            ...mockReport,
+            suggestions: [
+                {
+                    files: {
+                        "fileA.ts": () => [{ range: { begin: 0, end: 5 }, text: "def-A" }],
+                        "fileB.ts": () => [{ range: { begin: 0, end: 5 }, text: "def-B" }],
+                    },
+                    id: "suggestion-report",
+                },
+            ],
+        };
+        const result = resolveReportedSuggestions([report], {
+            ...mockTestCaseNormalized,
+            suggestions: [
+                {
+                    files: {
+                        "fileA.ts": [{ original: "abc-A", updated: "def-A" }],
+                        "fileB.ts": [{ original: "abc-B", updated: "def-B" }],
+                    },
+                    id: "suggestion-result",
+                },
+            ],
+        });
+        expect(result).toEqual([
+            {
+                files: {
+                    "fileA.ts": [
+                        {
+                            original: "abc-A",
+                            updated: "def-A",
+                        },
+                    ],
+                    "fileB.ts": [
+                        {
+                            original: "abc-B",
+                            updated: "def-B",
+                        },
+                    ],
+                },
+                id: "suggestion-report",
+            },
+        ]);
+    });
+});

package/lib/runTestCaseRule.d.ts

@@ -1,8 +1,8 @@
-import { AnyLanguage, AnyOptionalSchema, AnyRule, BaseAbout, InferredObject, LanguageFileFactory } from "@flint.fyi/core";
+import { AnyLanguage, AnyOptionalSchema, AnyRule, InferredObject, LanguageFileFactory, RuleAbout } from "@flint.fyi/core";
 import { CachedFactory } from "cached-factory";
 import { TestCaseNormalized } from "./normalizeTestCase.js";
 export interface TestCaseRuleConfiguration<OptionsSchema extends AnyOptionalSchema | undefined> {
     options?: InferredObject<OptionsSchema>;
-    rule: AnyRule<BaseAbout, OptionsSchema>;
+    rule: AnyRule<RuleAbout, OptionsSchema>;
 }
 export declare function runTestCaseRule<OptionsSchema extends AnyOptionalSchema | undefined>(fileFactories: CachedFactory<AnyLanguage, LanguageFileFactory>, { options, rule }: Required<TestCaseRuleConfiguration<OptionsSchema>>, { code, fileName }: TestCaseNormalized): import("@flint.fyi/core/lib/types/promises.js").PromiseOrSync<import("@flint.fyi/core").NormalizedReport[]>;

package/lib/types.d.ts

@@ -6,15 +6,32 @@ export interface InvalidTestCase<Options extends object | undefined = object | u
 export interface TestCase<Options extends object | undefined = object | undefined> {
     code: string;
     fileName?: string;
+    /**
+     * Run only this test case. Useful for debugging.
+     *
+     * Do not commit code with this flag set.
+     */
+    only?: boolean;
     options?: Options;
+    /**
+     * Skip running this test case. Useful for work-in-progress tests.
+     *
+     * Do not commit code with this flag set.
+     */
+    skip?: boolean;
 }
-export interface TestSuggestion {
-    files: Record<string, TestSuggestionFileCase[]>;
-    id: string;
-}
+export type TestSuggestion = TestSuggestionForFile | TestSuggestionForFiles;
 export interface TestSuggestionFileCase {
     original: string;
     updated: string;
 }
+export interface TestSuggestionForFile {
+    id: string;
+    updated: string;
+}
+export interface TestSuggestionForFiles {
+    files: Record<string, TestSuggestionFileCase[]>;
+    id: string;
+}
 export type ValidTestCase<Options extends object | undefined> = string | ValidTestCaseObject<Options>;
 export type ValidTestCaseObject<Options extends object | undefined> = TestCase<Options>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flint.fyi/rule-tester",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "description": "[Experimental] Rule unit tests for Flint.",
   "repository": {
     "type": "git",

package/src/RuleTester.ts

@@ -2,9 +2,9 @@ import {
 	AnyLanguage,
 	AnyOptionalSchema,
 	AnyRule,
-	BaseAbout,
 	InferredObject,
 	LanguageFileFactory,
+	RuleAbout,
 } from "@flint.fyi/core";
 import { CachedFactory } from "cached-factory";
 import assert from "node:assert";
@@ -13,12 +13,14 @@ import { createReportSnapshot } from "./createReportSnapshot.js";
 import { normalizeTestCase } from "./normalizeTestCase.js";
 import { resolveReportedSuggestions } from "./resolveReportedSuggestions.js";
 import { runTestCaseRule } from "./runTestCaseRule.js";
-import { InvalidTestCase, ValidTestCase } from "./types.js";
+import { InvalidTestCase, TestCase, ValidTestCase } from "./types.js";
 
 export interface RuleTesterOptions {
 	describe?: TesterSetupDescribe;
 	it?: TesterSetupIt;
+	only?: TesterSetupIt;
 	scope?: Record<string, unknown>;
+	skip?: TesterSetupIt;
 }
 
 export interface TestCases<Options extends object | undefined> {
@@ -40,19 +42,43 @@ export class RuleTester {
 	#fileFactories: CachedFactory<AnyLanguage, LanguageFileFactory>;
 	#testerOptions: Required<RuleTesterOptions>;
 
-	constructor({ describe, it, scope = globalThis }: RuleTesterOptions = {}) {
+	constructor({
+		describe,
+		it,
+		only,
+		scope = globalThis,
+		skip,
+	}: RuleTesterOptions = {}) {
 		this.#fileFactories = new CachedFactory((language: AnyLanguage) =>
 			language.prepare(),
 		);
+
+		it = defaultTo(it, scope, "it");
+
+		if (!skip && "skip" in it && typeof it.skip === "function") {
+			skip = it.skip as TesterSetupIt;
+		}
+		if (!only && "only" in it && typeof it.only === "function") {
+			only = it.only as TesterSetupIt;
+		}
+		if (!skip) {
+			throw new TypeError("RuleTester needs a `skip` function");
+		}
+		if (!only) {
+			throw new TypeError("RuleTester needs a `only` function");
+		}
+
 		this.#testerOptions = {
 			describe: defaultTo(describe, scope, "describe"),
-			it: defaultTo(it, scope, "it"),
+			it,
+			only,
 			scope,
+			skip,
 		};
 	}
 
 	describe<OptionsSchema extends AnyOptionalSchema | undefined>(
-		rule: AnyRule<BaseAbout, OptionsSchema>,
+		rule: AnyRule<RuleAbout, OptionsSchema>,
 		{ invalid, valid }: TestCases<InferredObject<OptionsSchema>>,
 	) {
 		this.#testerOptions.describe(rule.about.id, () => {
@@ -71,17 +97,17 @@ export class RuleTester {
 	}
 
 	#itInvalidCase<OptionsSchema extends AnyOptionalSchema | undefined>(
-		rule: AnyRule<BaseAbout, OptionsSchema>,
+		rule: AnyRule<RuleAbout, OptionsSchema>,
 		testCase: InvalidTestCase<InferredObject<OptionsSchema>>,
 	) {
 		const testCaseNormalized = normalizeTestCase(testCase);
 
-		this.#testerOptions.it(testCase.code, async () => {
+		this.#itTestCase(testCaseNormalized, async () => {
 			const reports = await runTestCaseRule(
 				this.#fileFactories,
 				{
 					// TODO: Figure out a way around the type assertion...
-					options: (testCase.options ?? {}) as InferredObject<OptionsSchema>,
+					options: testCase.options ?? ({} as InferredObject<OptionsSchema>),
 					rule,
 				},
 				testCaseNormalized,
@@ -98,15 +124,31 @@ export class RuleTester {
 		});
 	}
 
+	#itTestCase(testCase: TestCase, setup: () => Promise<void>) {
+		let test = testCase.only
+			? this.#testerOptions.only
+			: this.#testerOptions.it;
+
+		if (testCase.skip) {
+			if ("skip" in test && typeof test.skip === "function") {
+				test = test.skip as TesterSetupIt;
+			} else {
+				test = this.#testerOptions.skip;
+			}
+		}
+
+		test(testCase.code, setup);
+	}
+
 	#itValidCase<OptionsSchema extends AnyOptionalSchema | undefined>(
-		rule: AnyRule<BaseAbout, OptionsSchema>,
+		rule: AnyRule<RuleAbout, OptionsSchema>,
 		testCaseRaw: ValidTestCase<InferredObject<OptionsSchema>>,
 	) {
 		const testCase =
 			typeof testCaseRaw === "string" ? { code: testCaseRaw } : testCaseRaw;
 		const testCaseNormalized = normalizeTestCase(testCase);
 
-		this.#testerOptions.it(testCase.code, async () => {
+		this.#itTestCase(testCaseNormalized, async () => {
 			const reports = await runTestCaseRule(
 				this.#fileFactories,
 				{

package/src/createReportSnapshot.ts

@@ -25,7 +25,7 @@ function createReportSnapshotAt(sourceText: string, report: NormalizedReport) {
 		0,
 	);
 
-	const column = ifNegative(range.begin.raw - lineStartIndex - 2, 0);
+	const column = ifNegative(range.begin.raw - lineStartIndex - 1, 0);
 	const width = range.end.raw - range.begin.raw;
 
 	const injectionPrefix = " ".repeat(column);

package/src/predicates.ts

@@ -0,0 +1,7 @@
+import { TestSuggestion, TestSuggestionForFiles } from "./types.js";
+
+export function isTestSuggestionForFiles(
+	suggestion: TestSuggestion,
+): suggestion is TestSuggestionForFiles {
+	return "files" in suggestion;
+}