@flint.fyi/ts 0.13.1 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @flint/ts
 
+## 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
+
+- 0b80834: allow rules to indicate dependencies
+- Updated dependencies [0b80834]
+- Updated dependencies [63b61e5]
+  - @flint.fyi/core@0.13.5
+
 ## 0.13.1
 
 ### Patch Changes

package/lib/createTypeScriptFileFromProgram.js

@@ -28,7 +28,7 @@ export function createTypeScriptFileFromProgram(program, sourceFile) {
                 }),
             }));
         },
-        runRule(rule, options) {
+        async runRule(rule, options) {
             const reports = [];
             const context = {
                 report: (report) => {
@@ -41,10 +41,11 @@ export function createTypeScriptFileFromProgram(program, sourceFile) {
                 sourceFile,
                 typeChecker: program.getTypeChecker(),
             };
-            const visitors = rule.setup(context, options);
-            if (!visitors) {
+            const runtime = await rule.setup(context, options);
+            if (!runtime?.visitors) {
                 return reports;
             }
+            const { visitors } = runtime;
             const visit = (node) => {
                 visitors[ts.SyntaxKind[node.kind]]?.(node);
                 node.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/getTSNodeRange.d.ts

@@ -0,0 +1,3 @@
+import type * as ts from "typescript";
+import { CharacterReportRange } from "@flint.fyi/core";
+export declare function getTSNodeRange(node: ts.Node, sourceFile: ts.SourceFile): CharacterReportRange;

package/lib/{getNodeRange.js → getTSNodeRange.js}

@@ -1,4 +1,4 @@
-export function getNodeRange(node, sourceFile) {
+export function getTSNodeRange(node, sourceFile) {
     return {
         begin: node.getStart(sourceFile),
         end: node.getEnd(),

package/lib/index.d.ts

@@ -1,2 +1,3 @@
-export { typescriptLanguage } from "./language.js";
+export { getTSNodeRange } from "./getTSNodeRange.js";
+export * from "./language.js";
 export { ts } from "./plugin.js";

package/lib/index.js

@@ -1,2 +1,3 @@
-export { typescriptLanguage } from "./language.js";
+export { getTSNodeRange } from "./getTSNodeRange.js";
+export * from "./language.js";
 export { ts } from "./plugin.js";

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,15 +1,13 @@
-export declare const ts: import("@flint.fyi/core").Plugin<import("@flint.fyi/core").RuleAbout, {
-    all: string[];
-}, (import("@flint.fyi/core").Rule<{
-    readonly id: "consecutiveNonNullAssertions";
-    readonly preset: "logical";
-}, import("./nodes.js").TSNodesByName, import("./language.js").TypeScriptServices, "consecutiveNonNullAssertion", undefined> | import("@flint.fyi/core").Rule<{
+export declare const ts: import("@flint.fyi/core").Plugin<import("@flint.fyi/core").BaseAbout, string | undefined, [import("@flint.fyi/core").Rule<{
     readonly id: "forInArrays";
     readonly preset: "logical";
-}, import("./nodes.js").TSNodesByName, import("./language.js").TypeScriptServices, "forIn", undefined> | import("@flint.fyi/core").Rule<{
+}, import("./nodes.js").TSNodesByName, import("./language.js").TypeScriptServices, "forIn", undefined>, import("@flint.fyi/core").Rule<{
+    readonly id: "consecutiveNonNullAssertions";
+    readonly preset: "logical";
+}, import("./nodes.js").TSNodesByName, import("./language.js").TypeScriptServices, "consecutiveNonNullAssertion", undefined>, import("@flint.fyi/core").Rule<{
     readonly id: "namespaceDeclarations";
     readonly preset: "logical";
 }, import("./nodes.js").TSNodesByName, import("./language.js").TypeScriptServices, "preferModules", {
     readonly allowDeclarations: import("zod").ZodDefault<import("zod").ZodBoolean>;
     readonly allowDefinitionFiles: import("zod").ZodDefault<import("zod").ZodBoolean>;
-}>)[]>;
+}>]>;

package/lib/plugin.js

@@ -3,7 +3,7 @@ import consecutiveNonNullAssertions from "./rules/consecutiveNonNullAssertions.j
 import forInArrays from "./rules/forInArrays.js";
 import namespaceDeclarations from "./rules/namespaceDeclarations.js";
 export const ts = createPlugin({
-    globs: {
+    files: {
         all: ["**/*.{cjs,js,jsx,mjs,ts,tsx}"],
     },
     name: "ts",

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.js

@@ -17,22 +17,24 @@ export default typescriptLanguage.createRule({
     },
     setup(context) {
         return {
-            NonNullExpression(node) {
-                if (node.parent.kind !== ts.SyntaxKind.NonNullExpression) {
-                    return;
-                }
-                const range = {
-                    begin: node.end,
-                    end: node.parent.end + 1,
-                };
-                context.report({
-                    fix: {
+            visitors: {
+                NonNullExpression: (node) => {
+                    if (node.parent.kind !== ts.SyntaxKind.NonNullExpression) {
+                        return;
+                    }
+                    const range = {
+                        begin: node.end,
+                        end: node.parent.end + 1,
+                    };
+                    context.report({
+                        fix: {
+                            range,
+                            text: "",
+                        },
+                        message: "consecutiveNonNullAssertion",
                         range,
-                        text: "",
-                    },
-                    message: "consecutiveNonNullAssertion",
-                    range,
-                });
+                    });
+                },
             },
         };
     },

package/lib/rules/forInArrays.js

@@ -33,17 +33,19 @@ export default typescriptLanguage.createRule({
             return isTypeRecursive(type, (t) => t.getNumberIndexType() != null && hasNumberLikeLength(t));
         }
         return {
-            ForInStatement(node) {
-                const type = getConstrainedTypeAtLocation(node.expression, context.typeChecker);
-                if (isArrayLike(type)) {
-                    context.report({
-                        message: "forIn",
-                        range: {
-                            begin: node.getStart(),
-                            end: node.statement.getStart() - 1,
-                        },
-                    });
-                }
+            visitors: {
+                ForInStatement: (node) => {
+                    const type = getConstrainedTypeAtLocation(node.expression, context.typeChecker);
+                    if (isArrayLike(type)) {
+                        context.report({
+                            message: "forIn",
+                            range: {
+                                begin: node.getStart(),
+                                end: node.statement.getStart() - 1,
+                            },
+                        });
+                    }
+                },
             },
         };
     },

package/lib/rules/namespaceDeclarations.js

@@ -1,7 +1,7 @@
 import * as tsutils from "ts-api-utils";
 import * as ts from "typescript";
 import { z } from "zod";
-import { getNodeRange } from "../getNodeRange.js";
+import { getTSNodeRange } from "../getTSNodeRange.js";
 import { typescriptLanguage } from "../language.js";
 export default typescriptLanguage.createRule({
     about: {
@@ -28,20 +28,22 @@ export default typescriptLanguage.createRule({
             return;
         }
         return {
-            ModuleDeclaration(node) {
-                if (node.parent.kind !== ts.SyntaxKind.SourceFile ||
-                    node.name.kind !== ts.SyntaxKind.Identifier ||
-                    node.name.text === "global") {
-                    return;
-                }
-                if (allowDeclarations &&
-                    tsutils.includesModifier(node.modifiers, ts.SyntaxKind.DeclareKeyword)) {
-                    return;
-                }
-                context.report({
-                    message: "preferModules",
-                    range: getNodeRange(node.getChildAt(0), context.sourceFile),
-                });
+            visitors: {
+                ModuleDeclaration: (node) => {
+                    if (node.parent.kind !== ts.SyntaxKind.SourceFile ||
+                        node.name.kind !== ts.SyntaxKind.Identifier ||
+                        node.name.text === "global") {
+                        return;
+                    }
+                    if (allowDeclarations &&
+                        tsutils.includesModifier(node.modifiers, ts.SyntaxKind.DeclareKeyword)) {
+                        return;
+                    }
+                    context.report({
+                        message: "preferModules",
+                        range: getTSNodeRange(node.getChildAt(0), context.sourceFile),
+                    });
+                },
             },
         };
     },

package/package.json

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

package/src/createTypeScriptFileFromProgram.ts

@@ -1,6 +1,6 @@
 import {
 	LanguageFileDefinition,
-	NormalizedRuleReport,
+	NormalizedReport,
 	RuleReport,
 } from "@flint.fyi/core";
 import * as ts from "typescript";
@@ -42,8 +42,8 @@ export function createTypeScriptFileFromProgram(
 					}),
 				}));
 		},
-		runRule(rule, options) {
-			const reports: NormalizedRuleReport[] = [];
+		async runRule(rule, options) {
+			const reports: NormalizedReport[] = [];
 
 			const context = {
 				report: (report: RuleReport) => {
@@ -57,12 +57,13 @@ export function createTypeScriptFileFromProgram(
 				typeChecker: program.getTypeChecker(),
 			};
 
-			const visitors = rule.setup(context, options);
+			const runtime = await rule.setup(context, options);
 
-			if (!visitors) {
+			if (!runtime?.visitors) {
 				return reports;
 			}
 
+			const { visitors } = runtime;
 			const visit = (node: ts.Node) => {
 				visitors[ts.SyntaxKind[node.kind]]?.(node);
 

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,
+			        },
+			      },
+			    },
+			  ],
+			}
+		`);
+	});
+});

package/src/directives/parseDirectivesFromTypeScriptFile.ts

@@ -0,0 +1,31 @@
+import { DirectivesCollector } from "@flint.fyi/core";
+import * as tsutils from "ts-api-utils";
+import ts from "typescript";
+
+import { normalizeRange } from "../normalizeRange.js";
+
+export function parseDirectivesFromTypeScriptFile(sourceFile: ts.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/src/{getNodeRange.ts → getTSNodeRange.ts}

@@ -2,7 +2,7 @@ import type * as ts from "typescript";
 
 import { CharacterReportRange } from "@flint.fyi/core";
 
-export function getNodeRange(
+export function getTSNodeRange(
 	node: ts.Node,
 	sourceFile: ts.SourceFile,
 ): CharacterReportRange {