@flint.fyi/ts 0.15.0 → 0.18.0

package/lib/rules/tsComments.js

@@ -0,0 +1,130 @@
+import { ruleCreator } from "./ruleCreator.js";
+import { typescriptLanguage } from "@flint.fyi/typescript-language";
+import * as tsutils from "ts-api-utils";
+import { z } from "zod/v4";
+//#region src/rules/tsComments.ts
+const directiveConfigSchema = z.union([
+	z.literal(true),
+	z.literal(false),
+	z.literal("allow-with-description"),
+	z.object({ descriptionFormat: z.string().describe("A regular expression that the description must match for it to be considered valid.") })
+]);
+const options = {
+	allowTsExpectError: directiveConfigSchema.default(false).describe("Whether to allow `@ts-expect-error` directives, and with which restrictions."),
+	allowTsIgnore: directiveConfigSchema.default(false).describe("Whether to allow `@ts-ignore` directives."),
+	allowTsNocheck: directiveConfigSchema.default(false).describe("Whether to allow `@ts-nocheck` directives."),
+	minimumDescriptionLength: z.number().int().min(0).default(10).describe("The minimum length required for a description when using 'allow-with-description'.")
+};
+const tsDirectiveRegex = /^(?:\/\/\/?|\/\*)\s*@ts-(ignore|expect-error|nocheck|check)(?<description>[\s:*].*)?/i;
+function createFixedComment(text, fromDirective, toDirective) {
+	return text.replace(new RegExp(`@ts-${fromDirective}`, "i"), `@ts-${toDirective}`);
+}
+const directiveConfigKeys = new Map([
+	["ts-expect-error", "allowTsExpectError"],
+	["ts-ignore", "allowTsIgnore"],
+	["ts-nocheck", "allowTsNocheck"]
+]);
+var tsComments_default = ruleCreator.createRule(typescriptLanguage, {
+	about: {
+		description: "Reports problematic TypeScript comment directives or requires descriptions after directives.",
+		id: "tsComments",
+		presets: ["logical"]
+	},
+	messages: {
+		descriptionNotMatchPattern: {
+			primary: "The description for `{{ directive }}` does not match the preferred format: {{ format }}.",
+			secondary: ["This project requires comment directive descriptions to match the configured pattern.", "This helps maintain consistent and informative comments."],
+			suggestions: ["Update the description to match the required format.", "Check the rule configuration for the expected pattern."]
+		},
+		directiveComment: {
+			primary: "This project does not allow using `@{{ directive }}` to suppress compilation errors.",
+			secondary: ["Using TypeScript directive comments reduces the effectiveness of TypeScript's type system.", "Prefer fixing type errors or using targeted suppressions with descriptions."],
+			suggestions: ["Remove the directive and fix the underlying type error.", "If the suppression is necessary, add a description explaining why."]
+		},
+		preferExpectError: {
+			primary: "Prefer `@ts-expect-error` instead of `@ts-ignore`, as `@ts-expect-error` triggers type errors if it becomes unnecessary.",
+			secondary: ["`@ts-expect-error` will report if the next line has no error.", "This helps identify stale suppressions when errors are fixed."],
+			suggestions: ["Replace `@ts-ignore` with `@ts-expect-error`."]
+		},
+		requiresDescription: {
+			primary: "`@{{ directive }}` should include a description of at least {{ minimum }} characters.",
+			secondary: ["A description helps explain why the suppression is necessary.", "This improves code maintainability and documentation."],
+			suggestions: ["Add a description explaining why this suppression is needed."]
+		}
+	},
+	options,
+	setup(context) {
+		return { visitors: { SourceFile(node, { options }) {
+			function reportCommentDirective(comment, directive, data, messageDefault, messageIgnore = messageDefault) {
+				const range = {
+					begin: comment.pos,
+					end: comment.end
+				};
+				const [fix, message] = directive === "ts-ignore" ? [{
+					range,
+					text: createFixedComment(comment.text, "ignore", "expect-error")
+				}, messageIgnore] : [void 0, messageDefault];
+				context.report({
+					data,
+					fix,
+					message,
+					range
+				});
+			}
+			function getDirectiveOption(directive) {
+				const optionKey = directiveConfigKeys.get(directive);
+				if (!optionKey) return;
+				return options[optionKey];
+			}
+			const descriptionFormats = /* @__PURE__ */ new Map();
+			for (const directive of [
+				"ts-expect-error",
+				"ts-ignore",
+				"ts-nocheck"
+			]) {
+				const option = getDirectiveOption(directive);
+				if (typeof option === "object" && option.descriptionFormat) descriptionFormats.set(directive, new RegExp(option.descriptionFormat));
+			}
+			for (const comment of tsutils.iterateComments(node)) {
+				const match = tsDirectiveRegex.exec(comment.text);
+				if (!match) continue;
+				const directive = match[1].toLowerCase();
+				const description = (match.groups?.description ?? "").trim();
+				checkComment(comment, `ts-${directive}`, description);
+			}
+			function checkComment(comment, directive, description) {
+				const optionKey = directiveConfigKeys.get(directive);
+				if (!optionKey) return;
+				const config = options[optionKey];
+				switch (config) {
+					case "allow-with-description":
+						if (description.replace(/^[:\s*]+/, "").replace(/\s*\*\/$/, "").trim().length < options.minimumDescriptionLength) {
+							reportCommentDirective(comment, directive, {
+								directive,
+								minimum: options.minimumDescriptionLength
+							}, "requiresDescription");
+							return;
+						}
+						break;
+					case false: return;
+					case true:
+						reportCommentDirective(comment, directive, { directive }, "directiveComment", "preferExpectError");
+						return;
+					default:
+						if (typeof config === "object" && config.descriptionFormat) {
+							const format = descriptionFormats.get(directive);
+							if (format && !format.test(description)) reportCommentDirective(comment, directive, {
+								directive,
+								format: format.source
+							}, "descriptionNotMatchPattern");
+						}
+						break;
+				}
+			}
+		} } };
+	}
+});
+//#endregion
+export { tsComments_default as default };
+
+//# sourceMappingURL=tsComments.js.map

package/lib/rules/tslintComments.d.ts

@@ -0,0 +1,10 @@
+declare const _default: import("@flint.fyi/core").Rule<{
+    readonly description: "Reports TSLint disable/enable comments.";
+    readonly id: "tslintComments";
+    readonly presets: ["logical"];
+} & {
+    presets?: ("javascript" | "logical" | "logicalStrict" | "stylistic" | "stylisticStrict")[];
+    url: string;
+}, object, object, "tslintComment", import("@flint.fyi/core").AnyOptionalSchema>;
+export default _default;
+//# sourceMappingURL=tslintComments.d.ts.map

package/lib/rules/tslintComments.js

@@ -0,0 +1,36 @@
+import { ruleCreator } from "./ruleCreator.js";
+import { typescriptLanguage } from "@flint.fyi/typescript-language";
+import * as tsutils from "ts-api-utils";
+//#region src/rules/tslintComments.ts
+const tslintDirectiveRegex = /^\s*\/?tslint:(?:enable|disable)(?:-(?:line|next-line))?(?::|\s|$)/i;
+var tslintComments_default = ruleCreator.createRule(typescriptLanguage, {
+	about: {
+		description: "Reports TSLint disable/enable comments.",
+		id: "tslintComments",
+		presets: ["logical"]
+	},
+	messages: { tslintComment: {
+		primary: "TSLint is deprecated and its comments are no longer necessary.",
+		secondary: ["TSLint has been replaced by other linters such as Flint.", "These comments no longer have any effect."],
+		suggestions: ["Remove the TSLint comment.", "Replace it with the equivalent Flint comment if needed."]
+	} },
+	setup(context) {
+		return { visitors: { SourceFile: (node) => {
+			const comments = tsutils.iterateComments(node);
+			for (const { end, pos, text } of comments) {
+				const commentContent = text.replace(/^\/\/\s*/, "").replace(/^\/\*\s*/, "").replace(/\s*\*\/$/, "");
+				if (tslintDirectiveRegex.test(commentContent)) context.report({
+					message: "tslintComment",
+					range: {
+						begin: pos,
+						end
+					}
+				});
+			}
+		} } };
+	}
+});
+//#endregion
+export { tslintComments_default as default };
+
+//# sourceMappingURL=tslintComments.js.map

package/lib/rules/typeAssertionStyles.d.ts

@@ -0,0 +1,10 @@
+declare const _default: import("@flint.fyi/core").Rule<{
+    readonly description: "Reports angle-bracket type assertions.";
+    readonly id: "typeAssertionStyles";
+    readonly presets: ["stylistic"];
+} & {
+    presets?: ("javascript" | "logical" | "logicalStrict" | "stylistic" | "stylisticStrict")[];
+    url: string;
+}, object, object, "preferAs", import("@flint.fyi/core").AnyOptionalSchema>;
+export default _default;
+//# sourceMappingURL=typeAssertionStyles.d.ts.map

package/lib/rules/typeAssertionStyles.js

@@ -0,0 +1,32 @@
+import { ruleCreator } from "./ruleCreator.js";
+import { getTSNodeRange, typescriptLanguage } from "@flint.fyi/typescript-language";
+import ts from "typescript";
+//#region src/rules/typeAssertionStyles.ts
+function isConstAssertion(node, sourceFile) {
+	return node.type.kind === ts.SyntaxKind.TypeReference && node.type.typeName.kind === ts.SyntaxKind.Identifier && node.type.typeName.getText(sourceFile) === "const";
+}
+var typeAssertionStyles_default = ruleCreator.createRule(typescriptLanguage, {
+	about: {
+		description: "Reports angle-bracket type assertions.",
+		id: "typeAssertionStyles",
+		presets: ["stylistic"]
+	},
+	messages: { preferAs: {
+		primary: "Prefer `as` syntax for type assertions instead of legacy angle-brackets.",
+		secondary: ["Angle-bracket syntax is ambiguous with JSX.", "The 'as' syntax is clearer and works in all contexts."],
+		suggestions: ["Convert '<Type>value' to 'value as Type'."]
+	} },
+	setup(context) {
+		return { visitors: { TypeAssertionExpression(node, { sourceFile }) {
+			if (isConstAssertion(node, sourceFile)) return;
+			context.report({
+				message: "preferAs",
+				range: getTSNodeRange(node, sourceFile)
+			});
+		} } };
+	}
+});
+//#endregion
+export { typeAssertionStyles_default as default };
+
+//# sourceMappingURL=typeAssertionStyles.js.map

package/lib/rules/typeofComparisons.d.ts

@@ -1,7 +1,10 @@
 declare const _default: import("@flint.fyi/core").Rule<{
     readonly description: "Reports typeof expressions that compare impossible string literals.";
     readonly id: "typeofComparisons";
-    readonly preset: "untyped";
-}, import("../nodes.js").TSNodesByName, import("../language.js").TypeScriptFileServices, "invalidValue", undefined>;
+    readonly presets: ["javascript"];
+} & {
+    presets?: ("javascript" | "logical" | "logicalStrict" | "stylistic" | "stylisticStrict")[];
+    url: string;
+}, object, object, "invalidValue", import("@flint.fyi/core").AnyOptionalSchema>;
 export default _default;
 //# sourceMappingURL=typeofComparisons.d.ts.map

package/lib/rules/typeofComparisons.js

@@ -1,79 +1,58 @@
-import * as ts from "typescript";
-import { getTSNodeRange } from "../getTSNodeRange.js";
-import { typescriptLanguage } from "../language.js";
+import { ruleCreator } from "./ruleCreator.js";
+import { getTSNodeRange, typescriptLanguage } from "@flint.fyi/typescript-language";
+import { SyntaxKind } from "typescript";
+//#region src/rules/typeofComparisons.ts
 const validTypeofValues = new Set([
-    "bigint",
-    "boolean",
-    "function",
-    "number",
-    "object",
-    "string",
-    "symbol",
-    "undefined",
+	"bigint",
+	"boolean",
+	"function",
+	"number",
+	"object",
+	"string",
+	"symbol",
+	"undefined"
 ]);
-// TODO: Reuse a shared getStaticValue-style utility?
 function getStringValue(node) {
-    return ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)
-        ? node.text
-        : undefined;
+	return node.kind === SyntaxKind.StringLiteral || node.kind === SyntaxKind.NoSubstitutionTemplateLiteral ? node.text : void 0;
 }
 function getTypeofOperand(node) {
-    return ts.isTypeOfExpression(node) && node.expression;
+	return node.kind === SyntaxKind.TypeOfExpression && node.expression;
 }
-export default typescriptLanguage.createRule({
-    about: {
-        description: "Reports typeof expressions that compare impossible string literals.",
-        id: "typeofComparisons",
-        preset: "untyped",
-    },
-    messages: {
-        invalidValue: {
-            primary: "This string literal is not one that the typeof operator will ever produce.",
-            secondary: [
-                "The typeof operator returns one of a specific set of string values.",
-                "Comparing typeof to an invalid string is usually a typo and will never match.",
-                'The only valid values are: "bigint", "boolean", "function", "number", "object", "string", "symbol", and "undefined".',
-            ],
-            suggestions: [
-                "Check for typos and use one of the valid typeof return values.",
-            ],
-        },
-    },
-    setup(context) {
-        function checkComparison(node, sourceFile) {
-            const leftTypeofOperand = getTypeofOperand(node.left);
-            const rightTypeofOperand = getTypeofOperand(node.right);
-            let comparisonValue;
-            if (leftTypeofOperand) {
-                comparisonValue = node.right;
-            }
-            else if (rightTypeofOperand) {
-                comparisonValue = node.left;
-            }
-            else {
-                return;
-            }
-            const stringValue = getStringValue(comparisonValue);
-            if (stringValue != null && !validTypeofValues.has(stringValue)) {
-                context.report({
-                    message: "invalidValue",
-                    range: getTSNodeRange(comparisonValue, sourceFile),
-                });
-            }
-        }
-        return {
-            visitors: {
-                BinaryExpression: (node, { sourceFile }) => {
-                    if (node.operatorToken.kind === ts.SyntaxKind.EqualsEqualsToken ||
-                        node.operatorToken.kind === ts.SyntaxKind.EqualsEqualsEqualsToken ||
-                        node.operatorToken.kind === ts.SyntaxKind.ExclamationEqualsToken ||
-                        node.operatorToken.kind ===
-                            ts.SyntaxKind.ExclamationEqualsEqualsToken) {
-                        checkComparison(node, sourceFile);
-                    }
-                },
-            },
-        };
-    },
+var typeofComparisons_default = ruleCreator.createRule(typescriptLanguage, {
+	about: {
+		description: "Reports typeof expressions that compare impossible string literals.",
+		id: "typeofComparisons",
+		presets: ["javascript"]
+	},
+	messages: { invalidValue: {
+		primary: "This string literal is not one that the typeof operator will ever produce.",
+		secondary: [
+			"The typeof operator returns one of a specific set of string values.",
+			"Comparing typeof to an invalid string is usually a typo and will never match.",
+			"The only valid values are: \"bigint\", \"boolean\", \"function\", \"number\", \"object\", \"string\", \"symbol\", and \"undefined\"."
+		],
+		suggestions: ["Check for typos and use one of the valid typeof return values."]
+	} },
+	setup(context) {
+		function checkComparison(node, sourceFile) {
+			const leftTypeofOperand = getTypeofOperand(node.left);
+			const rightTypeofOperand = getTypeofOperand(node.right);
+			let comparisonValue;
+			if (leftTypeofOperand) comparisonValue = node.right;
+			else if (rightTypeofOperand) comparisonValue = node.left;
+			else return;
+			const stringValue = getStringValue(comparisonValue);
+			if (stringValue != null && !validTypeofValues.has(stringValue)) context.report({
+				message: "invalidValue",
+				range: getTSNodeRange(comparisonValue, sourceFile)
+			});
+		}
+		return { visitors: { BinaryExpression: (node, { sourceFile }) => {
+			if (node.operatorToken.kind === SyntaxKind.EqualsEqualsToken || node.operatorToken.kind === SyntaxKind.EqualsEqualsEqualsToken || node.operatorToken.kind === SyntaxKind.ExclamationEqualsToken || node.operatorToken.kind === SyntaxKind.ExclamationEqualsEqualsToken) checkComparison(node, sourceFile);
+		} } };
+	}
 });
+//#endregion
+export { typeofComparisons_default as default };
+
 //# sourceMappingURL=typeofComparisons.js.map

package/lib/rules/unassignedVariables.d.ts

@@ -1,7 +1,10 @@
 declare const _default: import("@flint.fyi/core").Rule<{
     readonly description: "Reports variables that are declared but never assigned a value.";
     readonly id: "unassignedVariables";
-    readonly preset: "untyped";
-}, import("../nodes.js").TSNodesByName, import("../language.js").TypeScriptFileServices, "noUnassigned", undefined>;
+    readonly presets: ["javascript"];
+} & {
+    presets?: ("javascript" | "logical" | "logicalStrict" | "stylistic" | "stylisticStrict")[];
+    url: string;
+}, object, object, "noUnassigned", import("@flint.fyi/core").AnyOptionalSchema>;
 export default _default;
 //# sourceMappingURL=unassignedVariables.d.ts.map

package/lib/rules/unassignedVariables.js

@@ -1,56 +1,37 @@
-import * as ts from "typescript";
-import { typescriptLanguage } from "../language.js";
-import { getModifyingReferences } from "../utils/getModifyingReferences.js";
-export default typescriptLanguage.createRule({
-    about: {
-        description: "Reports variables that are declared but never assigned a value.",
-        id: "unassignedVariables",
-        preset: "untyped",
-    },
-    messages: {
-        noUnassigned: {
-            primary: "Variable '{{ name }}' is declared but never assigned a value.",
-            secondary: [
-                "Declaring a variable without ever assigning it a value means it will always be `undefined`.",
-                "This is often a mistake, such as forgetting to initialize the variable or assign to it later.",
-            ],
-            suggestions: [
-                "Assign a value to the variable, either at declaration or before it is used.",
-                "If the variable is meant to be `undefined`, consider making that explicit for clarity.",
-            ],
-        },
-    },
-    setup(context) {
-        function hasAssignments(identifier, sourceFile, typeChecker) {
-            // TODO (#400): Switch to scope analysis
-            return !!getModifyingReferences(identifier, sourceFile, typeChecker)
-                .length;
-        }
-        return {
-            visitors: {
-                VariableDeclaration: (node, { sourceFile, typeChecker }) => {
-                    if (node.initializer || !ts.isIdentifier(node.name)) {
-                        return;
-                    }
-                    if (ts.isVariableDeclarationList(node.parent) &&
-                        !!(node.parent.flags & ts.NodeFlags.Const)) {
-                        return;
-                    }
-                    if (!hasAssignments(node.name, sourceFile, typeChecker)) {
-                        context.report({
-                            data: {
-                                name: node.name.text,
-                            },
-                            message: "noUnassigned",
-                            range: {
-                                begin: node.name.getStart(sourceFile),
-                                end: node.name.getEnd(),
-                            },
-                        });
-                    }
-                },
-            },
-        };
-    },
+import { ruleCreator } from "./ruleCreator.js";
+import { getModifyingReferences, typescriptLanguage } from "@flint.fyi/typescript-language";
+import ts, { SyntaxKind } from "typescript";
+//#region src/rules/unassignedVariables.ts
+var unassignedVariables_default = ruleCreator.createRule(typescriptLanguage, {
+	about: {
+		description: "Reports variables that are declared but never assigned a value.",
+		id: "unassignedVariables",
+		presets: ["javascript"]
+	},
+	messages: { noUnassigned: {
+		primary: "Variable '{{ name }}' is declared but never assigned a value.",
+		secondary: ["Declaring a variable without ever assigning it a value means it will always be `undefined`.", "This is often a mistake, such as forgetting to initialize the variable or assign to it later."],
+		suggestions: ["Assign a value to the variable, either at declaration or before it is used.", "If the variable is meant to be `undefined`, consider making that explicit for clarity."]
+	} },
+	setup(context) {
+		function hasAssignments(identifier, sourceFile, typeChecker) {
+			return !!getModifyingReferences(identifier, sourceFile, typeChecker).length;
+		}
+		return { visitors: { VariableDeclaration: (node, { sourceFile, typeChecker }) => {
+			if (node.initializer || node.name.kind !== SyntaxKind.Identifier) return;
+			if (node.parent.kind === SyntaxKind.VariableDeclarationList && !!(node.parent.flags & ts.NodeFlags.Const)) return;
+			if (!hasAssignments(node.name, sourceFile, typeChecker)) context.report({
+				data: { name: node.name.text },
+				message: "noUnassigned",
+				range: {
+					begin: node.name.getStart(sourceFile),
+					end: node.name.getEnd()
+				}
+			});
+		} } };
+	}
 });
+//#endregion
+export { unassignedVariables_default as default };
+
 //# sourceMappingURL=unassignedVariables.js.map

package/lib/rules/undefinedTypeofChecks.d.ts

@@ -0,0 +1,10 @@
+declare const _default: import("@flint.fyi/core").Rule<{
+    readonly description: "Reports typeof undefined checks.";
+    readonly id: "undefinedTypeofChecks";
+    readonly presets: ["stylistic"];
+} & {
+    presets?: ("javascript" | "logical" | "logicalStrict" | "stylistic" | "stylisticStrict")[];
+    url: string;
+}, object, object, "directComparison", import("@flint.fyi/core").AnyOptionalSchema>;
+export default _default;
+//# sourceMappingURL=undefinedTypeofChecks.d.ts.map

package/lib/rules/undefinedTypeofChecks.js

@@ -0,0 +1,41 @@
+import { ruleCreator } from "./ruleCreator.js";
+import { getTSNodeRange, typescriptLanguage } from "@flint.fyi/typescript-language";
+import { SyntaxKind } from "typescript";
+//#region src/rules/undefinedTypeofChecks.ts
+var undefinedTypeofChecks_default = ruleCreator.createRule(typescriptLanguage, {
+	about: {
+		description: "Reports typeof undefined checks.",
+		id: "undefinedTypeofChecks",
+		presets: ["stylistic"]
+	},
+	messages: { directComparison: {
+		primary: "This `typeof` comparison can be simplified to `=== undefined`.",
+		secondary: ["Checking whether a value is `undefined` can be done either with a `typeof` check or an equality comparison.", "Both amount to the same in modern code that does not override the global `undefined` value."],
+		suggestions: ["Replace with a direct `undefined` comparison."]
+	} },
+	setup(context) {
+		return { visitors: { BinaryExpression(node, { sourceFile }) {
+			const operator = node.operatorToken.kind;
+			if (operator !== SyntaxKind.EqualsEqualsEqualsToken && operator !== SyntaxKind.ExclamationEqualsEqualsToken && operator !== SyntaxKind.EqualsEqualsToken && operator !== SyntaxKind.ExclamationEqualsToken) return;
+			let typeofExpression;
+			if (node.left.kind === SyntaxKind.TypeOfExpression && node.right.kind === SyntaxKind.StringLiteral && node.right.text === "undefined") typeofExpression = node.left.expression;
+			else if (node.right.kind === SyntaxKind.TypeOfExpression && node.left.kind === SyntaxKind.StringLiteral && node.left.text === "undefined") typeofExpression = node.right.expression;
+			if (!typeofExpression) return;
+			const range = getTSNodeRange(node, sourceFile);
+			const expressionText = typeofExpression.getText(sourceFile);
+			const operatorText = node.operatorToken.getText(sourceFile);
+			context.report({
+				fix: {
+					range,
+					text: `${expressionText} ${operatorText} undefined`
+				},
+				message: "directComparison",
+				range
+			});
+		} } };
+	}
+});
+//#endregion
+export { undefinedTypeofChecks_default as default };
+
+//# sourceMappingURL=undefinedTypeofChecks.js.map

package/lib/rules/undefinedVariables.d.ts

@@ -1,7 +1,10 @@
 declare const _default: import("@flint.fyi/core").Rule<{
     readonly description: "Reports using variables that are not defined.";
     readonly id: "undefinedVariables";
-    readonly preset: "untyped";
-}, import("../nodes.js").TSNodesByName, import("../language.js").TypeScriptFileServices, "undefinedVariable", undefined>;
+    readonly presets: ["javascript"];
+} & {
+    presets?: ("javascript" | "logical" | "logicalStrict" | "stylistic" | "stylisticStrict")[];
+    url: string;
+}, object, object, "undefinedVariable", import("@flint.fyi/core").AnyOptionalSchema>;
 export default _default;
 //# sourceMappingURL=undefinedVariables.d.ts.map