@flint.fyi/ts 0.13.2 → 0.14.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @flint/ts
 
+## 0.14.1
+
+### Patch Changes
+
+- 27280d3: use first names for ts.SyntaxKind visitors, not aliases
+
+## 0.14.0
+
+### Minor Changes
+
+- 7d0d873: add // flint-\* comment directives
+
+### Patch Changes
+
+- Updated dependencies [b48f4a9]
+- Updated dependencies [7d0d873]
+- Updated dependencies [79f15da]
+  - @flint.fyi/core@0.15.0
+  - @flint.fyi/rule-tester@0.14.0
+
 ## 0.13.2
 
 ### Patch Changes

package/lib/createTypeScriptFileFromProgram.js

@@ -1,7 +1,9 @@
 import * as ts from "typescript";
 import { collectReferencedFilePaths } from "./collectReferencedFilePaths.js";
 import { formatDiagnostic } from "./formatDiagnostic.js";
+import { getFirstEnumValues } from "./getFirstEnumValues.js";
 import { normalizeRange } from "./normalizeRange.js";
+const NodeSyntaxKinds = getFirstEnumValues(ts.SyntaxKind);
 export function createTypeScriptFileFromProgram(program, sourceFile) {
     return {
         cache: {
@@ -47,7 +49,7 @@ export function createTypeScriptFileFromProgram(program, sourceFile) {
             }
             const { visitors } = runtime;
             const visit = (node) => {
-                visitors[ts.SyntaxKind[node.kind]]?.(node);
+                visitors[NodeSyntaxKinds[node.kind]]?.(node);
                 node.forEachChild(visit);
             };
             sourceFile.forEachChild(visit);

package/lib/createTypeScriptFileFromProjectService.d.ts

@@ -1,3 +1,10 @@
-import { LanguageFileDefinition } from "@flint.fyi/core";
 import * as ts from "typescript";
-export declare function createTypeScriptFileFromProjectService(filePathAbsolute: string, program: ts.Program, service: ts.server.ProjectService): LanguageFileDefinition;
+export declare function createTypeScriptFileFromProjectService(filePathAbsolute: string, program: ts.Program, service: ts.server.ProjectService): {
+    languageFile: {
+        [Symbol.dispose](): void;
+        cache?: import("@flint.fyi/core").LanguageFileCacheImpacts;
+        getDiagnostics?(): import("@flint.fyi/core").LanguageDiagnostics;
+        runRule<OptionsSchema extends import("@flint.fyi/core").AnyOptionalSchema | undefined = import("@flint.fyi/core").AnyOptionalSchema | undefined>(rule: import("@flint.fyi/core").AnyRuleDefinition<OptionsSchema>, options: import("@flint.fyi/core").InferredObject<OptionsSchema>): import("@flint.fyi/core/lib/types/promises.js").PromiseOrSync<import("@flint.fyi/core").NormalizedReport[]>;
+    };
+    sourceFile: ts.SourceFile;
+};

package/lib/createTypeScriptFileFromProjectService.js

@@ -9,9 +9,12 @@ export function createTypeScriptFileFromProjectService(filePathAbsolute, program
     log("Retrieved source file and type checker for file %s:", filePathAbsolute);
     const file = createTypeScriptFileFromProgram(program, sourceFile);
     return {
-        ...file,
-        [Symbol.dispose]() {
-            service.closeClientFile(filePathAbsolute);
+        languageFile: {
+            ...file,
+            [Symbol.dispose]() {
+                service.closeClientFile(filePathAbsolute);
+            },
         },
+        sourceFile,
     };
 }

package/lib/directives/parseDirectivesFromTypeScriptFile.d.ts

@@ -0,0 +1,5 @@
+import ts from "typescript";
+export declare function parseDirectivesFromTypeScriptFile(sourceFile: ts.SourceFile): {
+    directives: import("@flint.fyi/core").CommentDirective[];
+    reports: import("@flint.fyi/core").FileReport[];
+};

package/lib/directives/parseDirectivesFromTypeScriptFile.js

@@ -0,0 +1,21 @@
+import { DirectivesCollector } from "@flint.fyi/core";
+import * as tsutils from "ts-api-utils";
+import { normalizeRange } from "../normalizeRange.js";
+export function parseDirectivesFromTypeScriptFile(sourceFile) {
+    const collector = new DirectivesCollector(sourceFile.statements.at(0)?.getStart(sourceFile) ?? sourceFile.text.length);
+    tsutils.forEachComment(sourceFile, (fullText, sourceRange) => {
+        const commentText = fullText.slice(sourceRange.pos, sourceRange.end);
+        const match = /^\/\/\s*flint-(\S+)(?:\s+(.+))?/.exec(commentText);
+        if (!match) {
+            return;
+        }
+        const commentRange = {
+            begin: sourceRange.pos,
+            end: sourceRange.end,
+        };
+        const range = normalizeRange(commentRange, sourceFile);
+        const [type, selection] = match.slice(1);
+        collector.add(range, selection, type);
+    });
+    return collector.collect();
+}

package/lib/directives/parseDirectivesFromTypeScriptFile.test.d.ts

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

package/lib/directives/parseDirectivesFromTypeScriptFile.test.js

@@ -0,0 +1,91 @@
+import ts from "typescript";
+import { describe, expect, it } from "vitest";
+import { parseDirectivesFromTypeScriptFile } from "./parseDirectivesFromTypeScriptFile.js";
+describe(parseDirectivesFromTypeScriptFile, () => {
+    it("returns empty arrays when there are no directives", () => {
+        const sourceFile = ts.createSourceFile("test.ts", "// unrelated", ts.ScriptTarget.ESNext, true);
+        const actual = parseDirectivesFromTypeScriptFile(sourceFile);
+        expect(actual).toEqual({
+            directives: [],
+            reports: [],
+        });
+    });
+    it("returns parsed directives when there are comment directives", () => {
+        const sourceFile = ts.createSourceFile("test.ts", `
+                // flint-disable-file a
+                // flint-disable-next-line b
+                // flint-invalid
+            `, ts.ScriptTarget.ESNext, true);
+        const actual = parseDirectivesFromTypeScriptFile(sourceFile);
+        expect(actual).toMatchInlineSnapshot(`
+			{
+			  "directives": [
+			    {
+			      "range": {
+			        "begin": {
+			          "column": 16,
+			          "line": 1,
+			          "raw": 17,
+			        },
+			        "end": {
+			          "column": 39,
+			          "line": 1,
+			          "raw": 40,
+			        },
+			      },
+			      "selections": [
+			        "a",
+			      ],
+			      "type": "disable-file",
+			    },
+			    {
+			      "range": {
+			        "begin": {
+			          "column": 16,
+			          "line": 2,
+			          "raw": 57,
+			        },
+			        "end": {
+			          "column": 44,
+			          "line": 2,
+			          "raw": 85,
+			        },
+			      },
+			      "selections": [
+			        "b",
+			      ],
+			      "type": "disable-next-line",
+			    },
+			  ],
+			  "reports": [
+			    {
+			      "about": {
+			        "id": "commentDirectiveUnknown",
+			      },
+			      "message": {
+			        "primary": "Unknown comment directive type: "invalid".",
+			        "secondary": [
+			          "TODO",
+			        ],
+			        "suggestions": [
+			          "TODO",
+			        ],
+			      },
+			      "range": {
+			        "begin": {
+			          "column": 16,
+			          "line": 3,
+			          "raw": 102,
+			        },
+			        "end": {
+			          "column": 32,
+			          "line": 3,
+			          "raw": 118,
+			        },
+			      },
+			    },
+			  ],
+			}
+		`);
+    });
+});

package/lib/getFirstEnumValues.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Removes TypeScript enum values that alias earlier values.
+ * @param original Any TypeScript enum with numeric values.
+ * @returns A version of the enum with only the first occurrence of each value.
+ * @example
+ * Given the following enum:
+ * ```ts
+ * enum Example {
+ *   A = 1,
+ *   B = 2,
+ *   C = A
+ * }
+ * ```
+ * Its original value looks like:
+ * ```ts
+ * {
+ *   1: 'C', // <-- Points to 'C', the alias of 'A'
+ *   2: 'B',
+ *   A: 1,
+ *   B: 2,
+ *   C: 1,
+ * }
+ * ```
+ * Calling `getFirstEnumValues(Example)` would return:
+ * ```ts
+ * {
+ *   1: 'A', // <-- Corrected to the original 'A'
+ *   2: 'B',
+ *   A: 1,
+ *   B: 2,
+ *   C: 1,
+ * }
+ * ```
+ */
+export declare function getFirstEnumValues<Keys extends string, Values extends number, Original extends Record<Keys | Values, Keys | Values>>(original: Original): Original;

package/lib/getFirstEnumValues.js

@@ -0,0 +1,51 @@
+/**
+ * Removes TypeScript enum values that alias earlier values.
+ * @param original Any TypeScript enum with numeric values.
+ * @returns A version of the enum with only the first occurrence of each value.
+ * @example
+ * Given the following enum:
+ * ```ts
+ * enum Example {
+ *   A = 1,
+ *   B = 2,
+ *   C = A
+ * }
+ * ```
+ * Its original value looks like:
+ * ```ts
+ * {
+ *   1: 'C', // <-- Points to 'C', the alias of 'A'
+ *   2: 'B',
+ *   A: 1,
+ *   B: 2,
+ *   C: 1,
+ * }
+ * ```
+ * Calling `getFirstEnumValues(Example)` would return:
+ * ```ts
+ * {
+ *   1: 'A', // <-- Corrected to the original 'A'
+ *   2: 'B',
+ *   A: 1,
+ *   B: 2,
+ *   C: 1,
+ * }
+ * ```
+ */
+export function getFirstEnumValues(original) {
+    const result = {};
+    for (const key in original) {
+        if (typeof original[key] !== "number") {
+            continue;
+        }
+        if (!(key in result)) {
+            result[key] = original[key];
+        }
+        if (!(original[key] in result)) {
+            // 🤷 enums are tricky to type.
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any
+            result[original[key]] = key;
+        }
+    }
+    return result;
+}

package/lib/getFirstEnumValues.test.d.ts

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

package/lib/getFirstEnumValues.test.js

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { getFirstEnumValues } from "./getFirstEnumValues.js";
+describe("getFirstEnumValues", () => {
+    it("returns an empty object when given an empty enum", () => {
+        let Empty;
+        (function (Empty) {
+        })(Empty || (Empty = {}));
+        const result = getFirstEnumValues(Empty);
+        expect(result).toEqual({});
+    });
+    it("returns all original pairs when when given a non-repeating enum", () => {
+        let NonRepeating;
+        (function (NonRepeating) {
+            NonRepeating[NonRepeating["A"] = 1] = "A";
+            NonRepeating[NonRepeating["B"] = 2] = "B";
+            NonRepeating[NonRepeating["C"] = 3] = "C";
+        })(NonRepeating || (NonRepeating = {}));
+        const result = getFirstEnumValues(NonRepeating);
+        expect(result).toEqual({
+            1: "A",
+            2: "B",
+            3: "C",
+            A: 1,
+            B: 2,
+            C: 3,
+        });
+    });
+    it("returns the first key when when given a repeating-value enum", () => {
+        let Repeating;
+        (function (Repeating) {
+            Repeating[Repeating["A"] = 1] = "A";
+            Repeating[Repeating["B"] = 2] = "B";
+            // eslint-disable-next-line @typescript-eslint/prefer-literal-enum-member
+            Repeating[Repeating["C"] = 1] = "C";
+        })(Repeating || (Repeating = {}));
+        const result = getFirstEnumValues(Repeating);
+        expect(result).toEqual({
+            1: "A",
+            2: "B",
+            A: 1,
+            B: 2,
+            C: 1,
+        });
+    });
+});

package/lib/language.js

@@ -7,6 +7,7 @@ import path from "node:path";
 import * as ts from "typescript";
 import { createTypeScriptFileFromProgram } from "./createTypeScriptFileFromProgram.js";
 import { createTypeScriptFileFromProjectService } from "./createTypeScriptFileFromProjectService.js";
+import { prepareTypeScriptFile } from "./prepareTypeScriptFile.js";
 const log = debugForFile(import.meta.filename);
 const projectRoot = path.join(import.meta.dirname, "../..");
 export const typescriptLanguage = createLanguage({
@@ -42,12 +43,13 @@ export const typescriptLanguage = createLanguage({
             return program;
         });
         return {
-            prepareFileOnDisk: (filePathAbsolute) => {
+            prepareFromDisk: (filePathAbsolute) => {
                 const program = servicePrograms.get(filePathAbsolute);
                 seenPrograms.add(program);
-                return createTypeScriptFileFromProjectService(filePathAbsolute, program, service);
+                const { languageFile, sourceFile } = createTypeScriptFileFromProjectService(filePathAbsolute, program, service);
+                return prepareTypeScriptFile(languageFile, sourceFile);
             },
-            prepareFileVirtually: (filePathAbsolute, sourceText) => {
+            prepareFromVirtual: (filePathAbsolute, sourceText) => {
                 const environment = environments.get(filePathAbsolute);
                 environment.updateFile(filePathAbsolute, sourceText);
                 /* eslint-disable @typescript-eslint/no-non-null-assertion */
@@ -55,7 +57,8 @@ export const typescriptLanguage = createLanguage({
                 const program = environment.languageService.getProgram();
                 /* eslint-enable @typescript-eslint/no-non-null-assertion */
                 seenPrograms.add(program);
-                return createTypeScriptFileFromProgram(program, sourceFile);
+                const languageFile = createTypeScriptFileFromProgram(program, sourceFile);
+                return prepareTypeScriptFile(languageFile, sourceFile);
             },
         };
     },

package/lib/plugin.d.ts

@@ -1,10 +1,13 @@
 export declare const ts: import("@flint.fyi/core").Plugin<import("@flint.fyi/core").RuleAbout, string | undefined, [import("@flint.fyi/core").Rule<{
+    readonly description: "Reports iterating over an array with a for-in loop.";
     readonly id: "forInArrays";
     readonly preset: "logical";
 }, import("./nodes.js").TSNodesByName, import("./language.js").TypeScriptServices, "forIn", undefined>, import("@flint.fyi/core").Rule<{
+    readonly description: "Reports unnecessary extra non-null assertions.";
     readonly id: "consecutiveNonNullAssertions";
     readonly preset: "logical";
 }, import("./nodes.js").TSNodesByName, import("./language.js").TypeScriptServices, "consecutiveNonNullAssertion", undefined>, import("@flint.fyi/core").Rule<{
+    readonly description: "Reports using legacy `namespace` declarations.";
     readonly id: "namespaceDeclarations";
     readonly preset: "logical";
 }, import("./nodes.js").TSNodesByName, import("./language.js").TypeScriptServices, "preferModules", {

package/lib/prepareTypeScriptFile.d.ts

@@ -0,0 +1,7 @@
+import { LanguageFileDefinition } from "@flint.fyi/core";
+import ts from "typescript";
+export declare function prepareTypeScriptFile(languageFile: LanguageFileDefinition, sourceFile: ts.SourceFile): {
+    file: LanguageFileDefinition;
+    directives: import("@flint.fyi/core").CommentDirective[];
+    reports: import("@flint.fyi/core").FileReport[];
+};

package/lib/prepareTypeScriptFile.js

@@ -0,0 +1,7 @@
+import { parseDirectivesFromTypeScriptFile } from "./directives/parseDirectivesFromTypeScriptFile.js";
+export function prepareTypeScriptFile(languageFile, sourceFile) {
+    return {
+        ...parseDirectivesFromTypeScriptFile(sourceFile),
+        file: languageFile,
+    };
+}

package/lib/rules/consecutiveNonNullAssertions.d.ts

@@ -1,4 +1,5 @@
 declare const _default: import("@flint.fyi/core").Rule<{
+    readonly description: "Reports unnecessary extra non-null assertions.";
     readonly id: "consecutiveNonNullAssertions";
     readonly preset: "logical";
 }, import("../nodes.js").TSNodesByName, import("../language.js").TypeScriptServices, "consecutiveNonNullAssertion", undefined>;

package/lib/rules/consecutiveNonNullAssertions.js

@@ -2,6 +2,7 @@ import * as ts from "typescript";
 import { typescriptLanguage } from "../language.js";
 export default typescriptLanguage.createRule({
     about: {
+        description: "Reports unnecessary extra non-null assertions.",
         id: "consecutiveNonNullAssertions",
         preset: "logical",
     },
@@ -23,8 +24,8 @@ export default typescriptLanguage.createRule({
                         return;
                     }
                     const range = {
-                        begin: node.end,
-                        end: node.parent.end + 1,
+                        begin: node.end - 1,
+                        end: node.parent.end,
                     };
                     context.report({
                         fix: {

package/lib/rules/forInArrays.d.ts

@@ -1,4 +1,5 @@
 declare const _default: import("@flint.fyi/core").Rule<{
+    readonly description: "Reports iterating over an array with a for-in loop.";
     readonly id: "forInArrays";
     readonly preset: "logical";
 }, import("../nodes.js").TSNodesByName, import("../language.js").TypeScriptServices, "forIn", undefined>;

package/lib/rules/forInArrays.js

@@ -5,6 +5,7 @@ import { getConstrainedTypeAtLocation } from "./utils/getConstrainedType.js";
 import { isTypeRecursive } from "./utils/isTypeRecursive.js";
 export default typescriptLanguage.createRule({
     about: {
+        description: "Reports iterating over an array with a for-in loop.",
         id: "forInArrays",
         preset: "logical",
     },

package/lib/rules/namespaceDeclarations.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 declare const _default: import("@flint.fyi/core").Rule<{
+    readonly description: "Reports using legacy `namespace` declarations.";
     readonly id: "namespaceDeclarations";
     readonly preset: "logical";
 }, import("../nodes.js").TSNodesByName, import("../language.js").TypeScriptServices, "preferModules", {

package/lib/rules/namespaceDeclarations.js

@@ -5,6 +5,7 @@ import { getTSNodeRange } from "../getTSNodeRange.js";
 import { typescriptLanguage } from "../language.js";
 export default typescriptLanguage.createRule({
     about: {
+        description: "Reports using legacy `namespace` declarations.",
         id: "namespaceDeclarations",
         preset: "logical",
     },
@@ -20,8 +21,14 @@ export default typescriptLanguage.createRule({
         },
     },
     options: {
-        allowDeclarations: z.boolean().default(false),
-        allowDefinitionFiles: z.boolean().default(false),
+        allowDeclarations: z
+            .boolean()
+            .default(false)
+            .describe("Whether to allow namespaces declared with the `declare` keyword."),
+        allowDefinitionFiles: z
+            .boolean()
+            .default(false)
+            .describe("Whether to allow namespaces in `.d.ts` and other definition files."),
     },
     setup(context, { allowDeclarations, allowDefinitionFiles }) {
         if (allowDefinitionFiles && context.sourceFile.isDeclarationFile) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flint.fyi/ts",
-  "version": "0.13.2",
+  "version": "0.14.1",
   "description": "[Experimental] TypeScript language plugin for Flint.",
   "repository": {
     "type": "git",

package/src/createTypeScriptFileFromProgram.ts

@@ -1,14 +1,17 @@
 import {
 	LanguageFileDefinition,
-	NormalizedRuleReport,
+	NormalizedReport,
 	RuleReport,
 } from "@flint.fyi/core";
 import * as ts from "typescript";
 
 import { collectReferencedFilePaths } from "./collectReferencedFilePaths.js";
 import { formatDiagnostic } from "./formatDiagnostic.js";
+import { getFirstEnumValues } from "./getFirstEnumValues.js";
 import { normalizeRange } from "./normalizeRange.js";
 
+const NodeSyntaxKinds = getFirstEnumValues(ts.SyntaxKind);
+
 export function createTypeScriptFileFromProgram(
 	program: ts.Program,
 	sourceFile: ts.SourceFile,
@@ -43,7 +46,7 @@ export function createTypeScriptFileFromProgram(
 				}));
 		},
 		async runRule(rule, options) {
-			const reports: NormalizedRuleReport[] = [];
+			const reports: NormalizedReport[] = [];
 
 			const context = {
 				report: (report: RuleReport) => {
@@ -65,7 +68,7 @@ export function createTypeScriptFileFromProgram(
 
 			const { visitors } = runtime;
 			const visit = (node: ts.Node) => {
-				visitors[ts.SyntaxKind[node.kind]]?.(node);
+				visitors[NodeSyntaxKinds[node.kind]]?.(node);
 
 				node.forEachChild(visit);
 			};

package/src/createTypeScriptFileFromProjectService.ts

@@ -1,4 +1,3 @@
-import { LanguageFileDefinition } from "@flint.fyi/core";
 import { debugForFile } from "debug-for-file";
 import * as ts from "typescript";
 
@@ -10,7 +9,7 @@ export function createTypeScriptFileFromProjectService(
 	filePathAbsolute: string,
 	program: ts.Program,
 	service: ts.server.ProjectService,
-): LanguageFileDefinition {
+) {
 	const sourceFile = program.getSourceFile(filePathAbsolute);
 	if (!sourceFile) {
 		throw new Error(`Could not retrieve source file for: ${filePathAbsolute}`);
@@ -21,9 +20,12 @@ export function createTypeScriptFileFromProjectService(
 	const file = createTypeScriptFileFromProgram(program, sourceFile);
 
 	return {
-		...file,
-		[Symbol.dispose]() {
-			service.closeClientFile(filePathAbsolute);
+		languageFile: {
+			...file,
+			[Symbol.dispose]() {
+				service.closeClientFile(filePathAbsolute);
+			},
 		},
+		sourceFile,
 	};
 }

package/src/directives/parseDirectivesFromTypeScriptFile.test.ts

@@ -0,0 +1,108 @@
+import ts from "typescript";
+import { describe, expect, it } from "vitest";
+
+import { parseDirectivesFromTypeScriptFile } from "./parseDirectivesFromTypeScriptFile.js";
+
+describe(parseDirectivesFromTypeScriptFile, () => {
+	it("returns empty arrays when there are no directives", () => {
+		const sourceFile = ts.createSourceFile(
+			"test.ts",
+			"// unrelated",
+			ts.ScriptTarget.ESNext,
+			true,
+		);
+
+		const actual = parseDirectivesFromTypeScriptFile(sourceFile);
+
+		expect(actual).toEqual({
+			directives: [],
+			reports: [],
+		});
+	});
+
+	it("returns parsed directives when there are comment directives", () => {
+		const sourceFile = ts.createSourceFile(
+			"test.ts",
+			`
+                // flint-disable-file a
+                // flint-disable-next-line b
+                // flint-invalid
+            `,
+			ts.ScriptTarget.ESNext,
+			true,
+		);
+
+		const actual = parseDirectivesFromTypeScriptFile(sourceFile);
+
+		expect(actual).toMatchInlineSnapshot(`
+			{
+			  "directives": [
+			    {
+			      "range": {
+			        "begin": {
+			          "column": 16,
+			          "line": 1,
+			          "raw": 17,
+			        },
+			        "end": {
+			          "column": 39,
+			          "line": 1,
+			          "raw": 40,
+			        },
+			      },
+			      "selections": [
+			        "a",
+			      ],
+			      "type": "disable-file",
+			    },
+			    {
+			      "range": {
+			        "begin": {
+			          "column": 16,
+			          "line": 2,
+			          "raw": 57,
+			        },
+			        "end": {
+			          "column": 44,
+			          "line": 2,
+			          "raw": 85,
+			        },
+			      },
+			      "selections": [
+			        "b",
+			      ],
+			      "type": "disable-next-line",
+			    },
+			  ],
+			  "reports": [
+			    {
+			      "about": {
+			        "id": "commentDirectiveUnknown",
+			      },
+			      "message": {
+			        "primary": "Unknown comment directive type: "invalid".",
+			        "secondary": [
+			          "TODO",
+			        ],
+			        "suggestions": [
+			          "TODO",
+			        ],
+			      },
+			      "range": {
+			        "begin": {
+			          "column": 16,
+			          "line": 3,
+			          "raw": 102,
+			        },
+			        "end": {
+			          "column": 32,
+			          "line": 3,
+			          "raw": 118,
+			        },
+			      },
+			    },
+			  ],
+			}
+		`);
+	});
+});