@flint.fyi/ts 0.13.0

package/lib/rules/forInArrays.js

@@ -0,0 +1,50 @@
+import * as tsutils from "ts-api-utils";
+import * as ts from "typescript";
+import { typescriptLanguage } from "../language.js";
+import { getConstrainedTypeAtLocation } from "./utils/getConstrainedType.js";
+import { isTypeRecursive } from "./utils/isTypeRecursive.js";
+export default typescriptLanguage.createRule({
+    about: {
+        id: "forInArrays",
+        preset: "logical",
+    },
+    messages: {
+        forIn: {
+            primary: "For-in loops over arrays have surprising behavior that often leads to bugs.",
+            secondary: [
+                "A for-in loop (`for (const i in o)`) iterates over all enumerable properties of an object, including those that are not array indices.",
+                "This can lead to unexpected behavior when used with arrays, as it may include properties that are not part of the array's numeric indices.",
+                "It also returns the index key (`i`) as a string, which is not the expected numeric type for array indices.",
+            ],
+            suggestions: [
+                "Use a construct more suited for arrays, such as a for-of loop (`for (const i of o)`).",
+            ],
+        },
+    },
+    setup(context) {
+        function hasNumberLikeLength(type) {
+            const lengthProperty = type.getProperty("length");
+            if (lengthProperty == null) {
+                return false;
+            }
+            return tsutils.isTypeFlagSet(context.typeChecker.getTypeOfSymbol(lengthProperty), ts.TypeFlags.NumberLike);
+        }
+        function isArrayLike(type) {
+            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,
+                        },
+                    });
+                }
+            },
+        };
+    },
+});

package/lib/rules/forInArrays.test.d.ts

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

package/lib/rules/forInArrays.test.js

@@ -0,0 +1,24 @@
+import rule from "./forInArrays.js";
+import { ruleTester } from "./ruleTester.js";
+ruleTester.describe(rule, {
+    invalid: [
+        {
+            code: `
+declare const array: string[];
+for (const i in array) {}
+`,
+            snapshot: `
+declare const array: string[];
+for (const i in array) {}
+~~~~~~~~~~~~~~~~~~~~~~
+For-in loops over arrays have surprising behavior that often leads to bugs.
+`,
+        },
+    ],
+    valid: [
+        `
+declare const array: string[];
+for (const i of array) {}
+`,
+    ],
+});

package/lib/rules/namespaceDeclarations.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+declare const _default: import("@flint.fyi/core").Rule<{
+    readonly id: "namespaceDeclarations";
+    readonly preset: "logical";
+}, import("../nodes.js").TSNodesByName, import("../language.js").TypeScriptServices, "preferModules", {
+    readonly allowDeclarations: z.ZodDefault<z.ZodBoolean>;
+    readonly allowDefinitionFiles: z.ZodDefault<z.ZodBoolean>;
+}>;
+export default _default;

package/lib/rules/namespaceDeclarations.js

@@ -0,0 +1,48 @@
+import * as tsutils from "ts-api-utils";
+import * as ts from "typescript";
+import { z } from "zod";
+import { getNodeRange } from "../getNodeRange.js";
+import { typescriptLanguage } from "../language.js";
+export default typescriptLanguage.createRule({
+    about: {
+        id: "namespaceDeclarations",
+        preset: "logical",
+    },
+    messages: {
+        preferModules: {
+            primary: "Prefer using ECMAScript modules over legacy TypeScript namespaces.",
+            secondary: [
+                "Namespaces are a legacy feature of TypeScript that can lead to confusion and are not compatible with ECMAScript modules.",
+            ],
+            suggestions: [
+                "Modern codebases generally use `export` and `import` statements to define and use ECMAScript modules instead.",
+            ],
+        },
+    },
+    options: {
+        allowDeclarations: z.boolean().default(false),
+        allowDefinitionFiles: z.boolean().default(false),
+    },
+    setup(context, { allowDeclarations, allowDefinitionFiles }) {
+        if (allowDefinitionFiles && context.sourceFile.isDeclarationFile) {
+            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),
+                });
+            },
+        };
+    },
+});

package/lib/rules/namespaceDeclarations.test.d.ts

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

package/lib/rules/namespaceDeclarations.test.js

@@ -0,0 +1,40 @@
+import rule from "./namespaceDeclarations.js";
+import { ruleTester } from "./ruleTester.js";
+ruleTester.describe(rule, {
+    invalid: [
+        {
+            code: `
+namespace name {}
+`,
+            snapshot: `
+namespace name {}
+~~~~~~~~~
+Prefer using ECMAScript modules over legacy TypeScript namespaces.
+`,
+        },
+    ],
+    valid: [
+        `declare global {}`,
+        `declare module 'name' {}`,
+        {
+            code: `declare module name {}`,
+            options: { allowDeclarations: true },
+        },
+        {
+            code: `declare namespace name {}`,
+            options: { allowDeclarations: true },
+        },
+        {
+            code: `
+declare namespace outer {
+    namespace inner {}
+}`,
+            options: { allowDeclarations: true },
+        },
+        {
+            code: `namespace name {}`,
+            fileName: "file.d.ts",
+            options: { allowDefinitionFiles: true },
+        },
+    ],
+});

package/lib/rules/ruleTester.d.ts

@@ -0,0 +1,2 @@
+import { RuleTester } from "@flint.fyi/rule-tester";
+export declare const ruleTester: RuleTester;

package/lib/rules/ruleTester.js

@@ -0,0 +1,3 @@
+import { RuleTester } from "@flint.fyi/rule-tester";
+import { describe, it } from "vitest";
+export const ruleTester = new RuleTester({ describe, it });

package/lib/rules/utils/getConstrainedType.d.ts

@@ -0,0 +1,2 @@
+import * as ts from "typescript";
+export declare function getConstrainedTypeAtLocation(node: ts.Node, typeChecker: ts.TypeChecker): ts.Type;

package/lib/rules/utils/getConstrainedType.js

@@ -0,0 +1,4 @@
+export function getConstrainedTypeAtLocation(node, typeChecker) {
+    const type = typeChecker.getTypeAtLocation(node);
+    return typeChecker.getBaseConstraintOfType(type) ?? type;
+}

package/lib/rules/utils/isTypeRecursive.d.ts

@@ -0,0 +1,2 @@
+import * as ts from "typescript";
+export declare function isTypeRecursive(type: ts.Type, predicate: (t: ts.Type) => boolean): boolean;

package/lib/rules/utils/isTypeRecursive.js

@@ -0,0 +1,5 @@
+export function isTypeRecursive(type, predicate) {
+    return type.isUnionOrIntersection()
+        ? type.types.some((subType) => isTypeRecursive(subType, predicate))
+        : predicate(type);
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@flint.fyi/ts",
+  "version": "0.13.0",
+  "description": "[Experimental] TypeScript language plugin for Flint.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JoshuaKGoldberg/flint",
+    "directory": "packages/ts"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "JoshuaKGoldberg",
+    "email": "npm@joshuakgoldberg.com"
+  },
+  "type": "module",
+  "main": "./lib/index.js",
+  "dependencies": {
+    "@flint.fyi/core": "",
+    "@flint.fyi/rule-tester": "",
+    "@typescript-eslint/project-service": "^8.35.0",
+    "@typescript/vfs": "^1.6.1",
+    "cached-factory": "^0.1.0",
+    "debug-for-file": "^0.2.0",
+    "ts-api-utils": "^2.1.0",
+    "typescript": ">=5.8.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/collectReferencedFilePaths.ts

@@ -0,0 +1,37 @@
+import * as path from "node:path";
+import * as ts from "typescript";
+
+export function collectReferencedFilePaths(
+	program: ts.Program,
+	sourceFile: ts.SourceFile,
+) {
+	// TODO: Also handle inline import()s
+	// https://github.com/JoshuaKGoldberg/flint/issues/115
+	return sourceFile.statements
+		.filter(isImportDeclarationWithStringLiteral)
+		.map((statement) => {
+			const resolved = ts.resolveModuleName(
+				statement.moduleSpecifier.text,
+				sourceFile.fileName,
+				program.getCompilerOptions(),
+				// TODO: Eventually, the file system should be abstracted
+				// https://github.com/JoshuaKGoldberg/flint/issues/73
+				ts.sys,
+			);
+
+			return (
+				resolved.resolvedModule?.isExternalLibraryImport === false &&
+				path.relative(process.cwd(), resolved.resolvedModule.resolvedFileName)
+			);
+		})
+		.filter((resolvedFileName) => resolvedFileName !== false);
+}
+
+function isImportDeclarationWithStringLiteral(
+	statement: ts.Statement,
+): statement is ts.ImportDeclaration & { moduleSpecifier: ts.StringLiteral } {
+	return (
+		ts.isImportDeclaration(statement) &&
+		ts.isStringLiteral(statement.moduleSpecifier)
+	);
+}

package/src/createTypeScriptFileFromProgram.ts

@@ -0,0 +1,77 @@
+import {
+	LanguageFileDefinition,
+	NormalizedRuleReport,
+	RuleReport,
+} from "@flint.fyi/core";
+import * as ts from "typescript";
+
+import { collectReferencedFilePaths } from "./collectReferencedFilePaths.js";
+import { formatDiagnostic } from "./formatDiagnostic.js";
+import { normalizeRange } from "./normalizeRange.js";
+
+export function createTypeScriptFileFromProgram(
+	program: ts.Program,
+	sourceFile: ts.SourceFile,
+): LanguageFileDefinition {
+	return {
+		cache: {
+			dependencies: [
+				// TODO: Add support for multi-TSConfig workspaces.
+				// https://github.com/JoshuaKGoldberg/flint/issues/64 & more.
+				"tsconfig.json",
+
+				...collectReferencedFilePaths(program, sourceFile),
+			],
+		},
+		getDiagnostics() {
+			return ts
+				.getPreEmitDiagnostics(program, sourceFile)
+				.map((diagnostic) => ({
+					code: `TS${diagnostic.code}`,
+					text: formatDiagnostic({
+						...diagnostic,
+						// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+						length: diagnostic.length!,
+						message: ts.flattenDiagnosticMessageText(
+							diagnostic.messageText,
+							"\n",
+						),
+						name: `TS${diagnostic.code}`,
+						// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+						start: diagnostic.start!,
+					}),
+				}));
+		},
+		runRule(rule, options) {
+			const reports: NormalizedRuleReport[] = [];
+
+			const context = {
+				report: (report: RuleReport) => {
+					reports.push({
+						...report,
+						message: rule.messages[report.message],
+						range: normalizeRange(report.range, sourceFile),
+					});
+				},
+				sourceFile,
+				typeChecker: program.getTypeChecker(),
+			};
+
+			const visitors = rule.setup(context, options);
+
+			if (!visitors) {
+				return reports;
+			}
+
+			const visit = (node: ts.Node) => {
+				visitors[ts.SyntaxKind[node.kind]]?.(node);
+
+				node.forEachChild(visit);
+			};
+
+			sourceFile.forEachChild(visit);
+
+			return reports;
+		},
+	};
+}

package/src/createTypeScriptFileFromProjectService.ts

@@ -0,0 +1,29 @@
+import { LanguageFileDefinition } from "@flint.fyi/core";
+import { debugForFile } from "debug-for-file";
+import * as ts from "typescript";
+
+import { createTypeScriptFileFromProgram } from "./createTypeScriptFileFromProgram.js";
+
+const log = debugForFile(import.meta.filename);
+
+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}`);
+	}
+
+	log("Retrieved source file and type checker for file %s:", filePathAbsolute);
+
+	const file = createTypeScriptFileFromProgram(program, sourceFile);
+
+	return {
+		...file,
+		[Symbol.dispose]() {
+			service.closeClientFile(filePathAbsolute);
+		},
+	};
+}

package/src/formatDiagnostic.ts

@@ -0,0 +1,166 @@
+// Adapted from: https://github.com/ArnaudBarre/tsl/blob/742a6f1a956705239f2149f856b1f572ade79919/src/formatDiagnostic.ts
+// ...which notes:
+// Adapted from: https://github.com/microsoft/TypeScript/blob/78c16795cdee70b9d9f0f248b6dbb6ba50994a59/src/compiler/program.ts#L680-L811
+
+// eslint-disable-next-line @eslint-community/eslint-comments/disable-enable-pair
+/* eslint-disable @typescript-eslint/no-non-null-assertion */
+
+import ts, {
+	flattenDiagnosticMessageText,
+	getLineAndCharacterOfPosition,
+	getPositionOfLineAndCharacter,
+	type SourceFile,
+} from "typescript";
+
+export interface RawDiagnostic {
+	file?: ts.SourceFile;
+	length: number;
+	message: string;
+	name: string;
+	relatedInformation?: ts.DiagnosticRelatedInformation[];
+	start: number;
+}
+
+export function formatDiagnostic(diagnostic: RawDiagnostic) {
+	let output = "";
+
+	if (diagnostic.file !== undefined) {
+		output += formatLocation(diagnostic.file, diagnostic.start);
+		output += " - ";
+	}
+	output += color(diagnostic.name, COLOR.Grey);
+	output += ": ";
+	output += diagnostic.message;
+	if (diagnostic.file !== undefined) {
+		output += "\n";
+		output += formatCodeSpan(
+			diagnostic.file,
+			diagnostic.start,
+			diagnostic.length,
+			"",
+			COLOR.Red,
+		);
+	}
+	if (diagnostic.relatedInformation) {
+		output += "\n";
+		for (const {
+			file,
+			length,
+			messageText,
+			start,
+		} of diagnostic.relatedInformation) {
+			const indent = "  ";
+			if (file) {
+				output += "\n";
+				output += " " + formatLocation(file, start!);
+				output += formatCodeSpan(file, start!, length!, indent, COLOR.Cyan);
+			}
+			output += "\n";
+			output += indent + flattenDiagnosticMessageText(messageText, "\n");
+		}
+	}
+
+	return output;
+}
+
+function color(text: string, formatStyle: string) {
+	return formatStyle + text + resetEscapeSequence;
+}
+
+const gutterStyleSequence = "\u001b[7m";
+const ellipsis = "...";
+const gutterSeparator = " ";
+const resetEscapeSequence = "\u001b[0m";
+const COLOR = {
+	Blue: "\u001b[94m",
+	Cyan: "\u001b[96m",
+	Grey: "\u001b[90m",
+	Red: "\u001b[91m",
+	Yellow: "\u001b[93m",
+};
+
+function displayFilename(name: string) {
+	if (name.startsWith("./")) {
+		return name.slice(2);
+	}
+	return name.slice(process.cwd().length + 1);
+}
+
+function formatCodeSpan(
+	file: SourceFile,
+	start: number,
+	length: number,
+	indent: string,
+	squiggleColor: string,
+) {
+	const { character: firstLineChar, line: firstLine } =
+		getLineAndCharacterOfPosition(file, start);
+	const { character: lastLineChar, line: lastLine } =
+		getLineAndCharacterOfPosition(file, start + length);
+	const lastLineInFile = getLineAndCharacterOfPosition(
+		file,
+		file.text.length,
+	).line;
+	const hasMoreThanFiveLines = lastLine - firstLine >= 4;
+	// eslint-disable-next-line @typescript-eslint/restrict-plus-operands
+	let gutterWidth = (lastLine + 1 + "").length;
+	if (hasMoreThanFiveLines) {
+		gutterWidth = Math.max(ellipsis.length, gutterWidth);
+	}
+	let context = "";
+	for (let i = firstLine; i <= lastLine; i++) {
+		context += "\n";
+		if (hasMoreThanFiveLines && firstLine + 1 < i && i < lastLine - 1) {
+			context +=
+				indent +
+				color(ellipsis.padStart(gutterWidth), gutterStyleSequence) +
+				gutterSeparator +
+				"\n";
+			i = lastLine - 1;
+		}
+		const lineStart = getPositionOfLineAndCharacter(file, i, 0);
+		const lineEnd =
+			i < lastLineInFile
+				? getPositionOfLineAndCharacter(file, i + 1, 0)
+				: file.text.length;
+		let lineContent = file.text.slice(lineStart, lineEnd);
+		lineContent = lineContent.trimEnd();
+		lineContent = lineContent.replace(/\t/g, " ");
+		context +=
+			indent +
+			// eslint-disable-next-line @typescript-eslint/restrict-plus-operands
+			color((i + 1 + "").padStart(gutterWidth), gutterStyleSequence) +
+			gutterSeparator;
+		context += lineContent + "\n";
+		context +=
+			indent +
+			color("".padStart(gutterWidth), gutterStyleSequence) +
+			gutterSeparator;
+		context += squiggleColor;
+		if (i === firstLine) {
+			const lastCharForLine = i === lastLine ? lastLineChar : void 0;
+			context += lineContent.slice(0, firstLineChar).replace(/\S/g, " ");
+			context += lineContent
+				.slice(firstLineChar, lastCharForLine)
+				.replace(/./g, "~");
+		} else if (i === lastLine) {
+			context += lineContent.slice(0, lastLineChar).replace(/./g, "~");
+		} else {
+			context += lineContent.replace(/./g, "~");
+		}
+		context += resetEscapeSequence;
+	}
+	return context;
+}
+
+function formatLocation(file: SourceFile, start: number): string {
+	const { character, line } = getLineAndCharacterOfPosition(file, start);
+	const relativeFileName = displayFilename(file.fileName);
+	let output = "";
+	output += color(relativeFileName, COLOR.Cyan);
+	output += ":";
+	output += color(`${line + 1}`, COLOR.Yellow);
+	output += ":";
+	output += color(`${character + 1}`, COLOR.Yellow);
+	return output;
+}

package/src/getNodeRange.ts

@@ -0,0 +1,13 @@
+import type * as ts from "typescript";
+
+import { CharacterReportRange } from "@flint.fyi/core";
+
+export function getNodeRange(
+	node: ts.Node,
+	sourceFile: ts.SourceFile,
+): CharacterReportRange {
+	return {
+		begin: node.getStart(sourceFile),
+		end: node.getEnd(),
+	};
+}

package/src/index.ts

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

package/src/language.ts

@@ -0,0 +1,112 @@
+import { createLanguage } from "@flint.fyi/core";
+import { createProjectService } from "@typescript-eslint/project-service";
+import {
+	createFSBackedSystem,
+	createVirtualTypeScriptEnvironment,
+} from "@typescript/vfs";
+import { CachedFactory } from "cached-factory";
+import { debugForFile } from "debug-for-file";
+import path from "node:path";
+import * as ts from "typescript";
+
+import { createTypeScriptFileFromProgram } from "./createTypeScriptFileFromProgram.js";
+import { createTypeScriptFileFromProjectService } from "./createTypeScriptFileFromProjectService.js";
+import { TSNodesByName } from "./nodes.js";
+
+const log = debugForFile(import.meta.filename);
+
+const projectRoot = path.join(import.meta.dirname, "../..");
+
+export interface TypeScriptServices {
+	sourceFile: ts.SourceFile;
+	typeChecker: ts.TypeChecker;
+}
+
+export const typescriptLanguage = createLanguage<
+	TSNodesByName,
+	TypeScriptServices
+>({
+	about: {
+		name: "TypeScript",
+	},
+	prepare: () => {
+		const { service } = createProjectService();
+		const seenPrograms = new Set<ts.Program>();
+
+		const environments = new CachedFactory((filePathAbsolute: string) => {
+			const system = createFSBackedSystem(
+				new Map([[filePathAbsolute, "// ..."]]),
+				projectRoot,
+				ts,
+			);
+
+			return createVirtualTypeScriptEnvironment(
+				system,
+				[filePathAbsolute],
+				ts,
+				{
+					skipLibCheck: true,
+					target: ts.ScriptTarget.ESNext,
+				},
+			);
+		});
+
+		const servicePrograms = new CachedFactory((filePathAbsolute: string) => {
+			log("Opening client file:", filePathAbsolute);
+			service.openClientFile(filePathAbsolute);
+
+			log("Retrieving client services:", filePathAbsolute);
+			const scriptInfo = service.getScriptInfo(filePathAbsolute);
+			if (!scriptInfo) {
+				throw new Error(
+					`Could not find script info for file: ${filePathAbsolute}`,
+				);
+			}
+
+			const defaultProject = service.getDefaultProjectForFile(
+				scriptInfo.fileName,
+				true,
+			);
+			if (!defaultProject) {
+				throw new Error(
+					`Could not find default project for file: ${filePathAbsolute}`,
+				);
+			}
+
+			const program = defaultProject.getLanguageService(true).getProgram();
+			if (!program) {
+				throw new Error(
+					`Could not retrieve program for file: ${filePathAbsolute}`,
+				);
+			}
+
+			return program;
+		});
+
+		return {
+			prepareFileOnDisk: (filePathAbsolute) => {
+				const program = servicePrograms.get(filePathAbsolute);
+
+				seenPrograms.add(program);
+
+				return createTypeScriptFileFromProjectService(
+					filePathAbsolute,
+					program,
+					service,
+				);
+			},
+			prepareFileVirtually: (filePathAbsolute, sourceText) => {
+				const environment = environments.get(filePathAbsolute);
+				environment.updateFile(filePathAbsolute, sourceText);
+				/* eslint-disable @typescript-eslint/no-non-null-assertion */
+				const sourceFile = environment.getSourceFile(filePathAbsolute)!;
+				const program = environment.languageService.getProgram()!;
+				/* eslint-enable @typescript-eslint/no-non-null-assertion */
+
+				seenPrograms.add(program);
+
+				return createTypeScriptFileFromProgram(program, sourceFile);
+			},
+		};
+	},
+});