@flint.fyi/ts 0.14.0 → 0.14.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @flint/ts
 
+## 0.14.2
+
+### Patch Changes
+
+- 6415134: feat: implement debuggerStatements rule for TypeScript plugin
+- Updated dependencies [b58d145]
+  - @flint.fyi/rule-tester@0.14.1
+
+## 0.14.1
+
+### Patch Changes
+
+- 27280d3: use first names for ts.SyntaxKind visitors, not aliases
+
 ## 0.14.0
 
 ### Minor 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/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/plugin.d.ts

@@ -1,13 +1,24 @@
-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<{
+export declare const ts: import("@flint.fyi/core").Plugin<import("@flint.fyi/core").RuleAbout, string | 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 debugger statements.";
+    readonly id: "debuggerStatements";
+    readonly preset: "logical";
+}, import("./nodes.js").TSNodesByName, import("./language.js").TypeScriptServices, "noDebugger", 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 using legacy `namespace` declarations.";
     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>;
-}>]>;
+}>, import("@flint.fyi/core").Rule<{
+    readonly description: "Reports using octal escape sequences in string literals.";
+    readonly id: "octalEscapes";
+    readonly preset: "logical";
+}, import("./nodes.js").TSNodesByName, import("./language.js").TypeScriptServices, "noOctalEscape", undefined>]>;

package/lib/plugin.js

@@ -1,11 +1,19 @@
 import { createPlugin } from "@flint.fyi/core";
 import consecutiveNonNullAssertions from "./rules/consecutiveNonNullAssertions.js";
+import debuggerStatements from "./rules/debuggerStatements.js";
 import forInArrays from "./rules/forInArrays.js";
 import namespaceDeclarations from "./rules/namespaceDeclarations.js";
+import octalEscapes from "./rules/octalEscapes.js";
 export const ts = createPlugin({
     files: {
         all: ["**/*.{cjs,js,jsx,mjs,ts,tsx}"],
     },
     name: "ts",
-    rules: [forInArrays, consecutiveNonNullAssertions, namespaceDeclarations],
+    rules: [
+        consecutiveNonNullAssertions,
+        debuggerStatements,
+        forInArrays,
+        namespaceDeclarations,
+        octalEscapes,
+    ],
 });

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/debuggerStatements.d.ts

@@ -0,0 +1,6 @@
+declare const _default: import("@flint.fyi/core").Rule<{
+    readonly description: "Reports using debugger statements.";
+    readonly id: "debuggerStatements";
+    readonly preset: "logical";
+}, import("../nodes.js").TSNodesByName, import("../language.js").TypeScriptServices, "noDebugger", undefined>;
+export default _default;

package/lib/rules/debuggerStatements.js

@@ -0,0 +1,43 @@
+import { typescriptLanguage } from "../language.js";
+export default typescriptLanguage.createRule({
+    about: {
+        description: "Reports using debugger statements.",
+        id: "debuggerStatements",
+        preset: "logical",
+    },
+    messages: {
+        noDebugger: {
+            primary: "Debugger statements should not be used in production code.",
+            secondary: [
+                "The `debugger` statement causes the JavaScript runtime to pause execution and start a debugger if one is available, such as when browser developer tools are open.",
+                "This can be useful during development, but should not be left in production code.",
+            ],
+            suggestions: [
+                "Remove the `debugger` statement before shipping this code to users.",
+            ],
+        },
+    },
+    setup(context) {
+        return {
+            visitors: {
+                DebuggerStatement: (node) => {
+                    const range = {
+                        begin: node.getStart(),
+                        end: node.getEnd(),
+                    };
+                    context.report({
+                        message: "noDebugger",
+                        range,
+                        suggestions: [
+                            {
+                                id: "removeDebugger",
+                                range,
+                                text: "",
+                            },
+                        ],
+                    });
+                },
+            },
+        };
+    },
+});

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

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

package/lib/rules/debuggerStatements.test.js

@@ -0,0 +1,80 @@
+import rule from "./debuggerStatements.js";
+import { ruleTester } from "./ruleTester.js";
+ruleTester.describe(rule, {
+    invalid: [
+        {
+            code: `
+debugger;
+`,
+            snapshot: `
+debugger;
+~~~~~~~~~
+Debugger statements should not be used in production code.
+`,
+            suggestions: [
+                {
+                    id: "removeDebugger",
+                    updated: `
+
+`,
+                },
+            ],
+        },
+        {
+            code: `
+function test() {
+	debugger;
+}
+`,
+            snapshot: `
+function test() {
+	debugger;
+ ~~~~~~~~~
+ Debugger statements should not be used in production code.
+}
+`,
+            suggestions: [
+                {
+                    id: "removeDebugger",
+                    updated: `
+function test() {
+	
+}
+`,
+                },
+            ],
+        },
+        {
+            code: `
+if (condition) {
+	debugger;
+}
+`,
+            snapshot: `
+if (condition) {
+	debugger;
+ ~~~~~~~~~
+ Debugger statements should not be used in production code.
+}
+`,
+            suggestions: [
+                {
+                    id: "removeDebugger",
+                    updated: `
+if (condition) {
+	
+}
+`,
+                },
+            ],
+        },
+    ],
+    valid: [
+        `console.log("debugging");`,
+        `function test() { console.log("test"); }`,
+        `for (let i = 0; i < 10; i++) { break; }`,
+        `for (let i = 0; i < 10; i++) { continue; }`,
+        `function test() { return; }`,
+        `throw new Error("test");`,
+    ],
+});

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/lib/rules/octalEscapes.d.ts

@@ -0,0 +1,6 @@
+declare const _default: import("@flint.fyi/core").Rule<{
+    readonly description: "Reports using octal escape sequences in string literals.";
+    readonly id: "octalEscapes";
+    readonly preset: "logical";
+}, import("../nodes.js").TSNodesByName, import("../language.js").TypeScriptServices, "noOctalEscape", undefined>;
+export default _default;

package/lib/rules/octalEscapes.js

@@ -0,0 +1,71 @@
+import { typescriptLanguage } from "../language.js";
+/**
+ * Finds the position and length of an octal escape sequence in a string.
+ * Returns undefined if no octal escape is found.
+ */
+function findOctalEscape(text) {
+    // Remove quotes from the string literal
+    const content = text.slice(1, -1);
+    // Match octal escapes: \0 followed by [0-7], or \1-7 optionally followed by [0-7]
+    // But exclude escaped backslashes (\\)
+    const octalEscapePattern = /(?<!\\)\\0[0-7]|(?<!\\)\\[1-7][0-7]*/;
+    const match = octalEscapePattern.exec(content);
+    if (!match) {
+        return undefined;
+    }
+    // Add 1 to account for the opening quote
+    return {
+        index: match.index + 1,
+        length: match[0].length,
+    };
+}
+export default typescriptLanguage.createRule({
+    about: {
+        description: "Reports using octal escape sequences in string literals.",
+        id: "octalEscapes",
+        preset: "logical",
+    },
+    messages: {
+        noOctalEscape: {
+            primary: "Prefer hexadecimal or Unicode escape sequences over legacy octal escape sequences.",
+            secondary: [
+                "Octal escape sequences (e.g., `\\01`, `\\02`, `\\377`) are a deprecated feature in JavaScript that can lead to confusion and are forbidden in strict mode and template literals.",
+                "They are less readable than their modern alternatives and can cause portability issues.",
+            ],
+            suggestions: [
+                "Use hexadecimal escape sequences (e.g., `\\x01`) or Unicode escape sequences (e.g., `\\u0001`) instead.",
+            ],
+        },
+    },
+    setup(context) {
+        function checkNode(node) {
+            const text = node.getText(context.sourceFile);
+            const octalEscape = findOctalEscape(text);
+            if (!octalEscape) {
+                return;
+            }
+            const nodeStart = node.getStart(context.sourceFile);
+            context.report({
+                message: "noOctalEscape",
+                range: {
+                    begin: nodeStart + octalEscape.index,
+                    end: nodeStart + octalEscape.index + octalEscape.length,
+                },
+            });
+        }
+        return {
+            visitors: {
+                NoSubstitutionTemplateLiteral: checkNode,
+                StringLiteral: checkNode,
+                TemplateExpression: (node) => {
+                    // Check the head of the template
+                    checkNode(node.head);
+                    // Check each template span
+                    for (const span of node.templateSpans) {
+                        checkNode(span.literal);
+                    }
+                },
+            },
+        };
+    },
+});

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

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