.eslintrc.js

/* eslint-disable @typescript-eslint/no-require-imports */
/* eslint-disable import/no-commonjs */
const fs = require("fs");
const path = require("path");

const fg = require("fast-glob");

const pkgNames = fg
    .globSync(path.join(__dirname, "packages/*/package.json"))
    .map((pkgJsonPath) => path.basename(path.dirname(pkgJsonPath)));

const pkgAliases = pkgNames.map((pkgName) => {
    return [`@khanacademy/${pkgName}`, `./packages/${pkgName}/src/index.js`];
});

const vendorAliases = fs
    .readdirSync(path.join(__dirname, "vendor"))
    .map((name) => {
        return [name, `./vendor/${name}`];
    });

const allAliases = [...pkgAliases, ...vendorAliases];

function banImportExtension(extension) {
    const message = `Unexpected use of file extension (.${extension}) in import`;
    const literalAttributeMatcher = `Literal[value=/\\.${extension}$/]`;
    return [
        {
            // import foo from 'bar.js';
            selector: `ImportDeclaration > ${literalAttributeMatcher}.source`,
            message,
        },
        {
            // const foo = import('bar.js');
            selector: `ImportExpression > ${literalAttributeMatcher}.source`,
            message,
        },
        {
            // type Foo = typeof import('bar.js');
            selector: `TSImportType > TSLiteralType > ${literalAttributeMatcher}`,
            message,
        },
        {
            // const foo = require('foo.js');
            selector: `CallExpression[callee.name = "require"] > ${literalAttributeMatcher}.arguments`,
            message,
        },
    ];
}

/**
 * Import restrictions shared by the base config and the per-package
 * overrides below. An override *replaces* `no-restricted-imports` rather
 * than merging with it, so anything adding restrictions must carry these.
 */
const restrictedImportPaths = [
    /** Wonder Blocks Restricted Imports */
    {
        name: "@khanacademy/wonder-blocks-tokens",
        importNames: ["color"],
        message:
            "Please use semanticColor instead. See https://khanacademy.atlassian.net/wiki/spaces/WB/pages/4049666283/Core or https://khan.github.io/wonder-blocks/?path=/docs/foundations-using-color--docs&globals=theme:thunderblocks",
    },
    {
        name: "@khanacademy/wonder-blocks-tabs",
        importNames: ["NavigationTabs", "Tabs"],
        message:
            "Use WB ResponsiveNavigationTabs or ResponsiveTabs for responsive behaviour. They render NavigationTabs or Tabs by default and switch to a dropdown when space is limited - test both layouts. See https://khan.github.io/wonder-blocks/?path=/docs/packages-tabs-overview--docs. \n\nIf responsiveness isn't needed, ignore this rule for that import.",
    },
    {
        name: "@khanacademy/wonder-blocks-typography",
        importNames: [
            "Title",
            "HeadingLarge",
            "HeadingMedium",
            "HeadingSmall",
            "HeadingXSmall",
            "Tagline",
        ],
        message:
            "Please use the WB Heading component instead. See https://khan.github.io/wonder-blocks/?path=/docs/packages-typography-heading-new--docs",
    },
    {
        name: "@khanacademy/wonder-blocks-typography",
        importNames: [
            "Body",
            "LabelLarge",
            "LabelMedium",
            "LabelSmall",
            "LabelXSmall",
            "Caption",
            "Footnote",
        ],
        message:
            "Please use the WB BodyText component instead. See https://khan.github.io/wonder-blocks/?path=/docs/packages-typography-bodytext-new--docs",
    },
];

/**
 * Forbid a package from importing itself by name.
 *
 * A self-import resolves through the package's own `exports` map, so Rollup
 * treats it as a second entry into the package and inlines another copy of
 * whatever it pulls in. Nothing errors, so the duplication is invisible — and
 * for a module holding state (a registry, a singleton) the two copies diverge.
 */
const noSelfPackageImports = pkgNames.map((pkgName) => ({
    files: [`packages/${pkgName}/**`],
    rules: {
        "no-restricted-imports": [
            "error",
            {
                paths: restrictedImportPaths,
                patterns: [
                    {
                        group: [
                            `@khanacademy/${pkgName}`,
                            `@khanacademy/${pkgName}/*`,
                        ],
                        message:
                            "Reach this package's own modules by relative path.",
                    },
                ],
            },
        ],
    },
}));

module.exports = {
    extends: [
        "@khanacademy",
        "@khanacademy/eslint-config/a11y",
        "plugin:@khanacademy/wonder-blocks/strict", // config from @khanacademy/eslint-plugin-wonder-blocks
        "plugin:react/recommended",
        // This config includes rules from storybook to enforce story best
        // practices
        "plugin:storybook/recommended",
        // This config includes rules from @testing-library/jest-dom as well
        "plugin:testing-library/react",
    ],
    parser: "@typescript-eslint/parser",
    plugins: [
        "disable",
        "import",
        "jest",
        "jsdoc",
        "monorepo",
        "promise",
        "react",
        "react-hooks",
        "react-native",
        "@khanacademy/wonder-blocks",
    ],
    settings: {
        "import/resolver": {
            typescript: {
                project: ["tsconfig.json"],
                extensions: [".js", ".jsx", ".ts", ".tsx"],
                moduleDirectory: ["node_modules"],
            },
            alias: {
                map: allAliases,
                extensions: [".ts", ".tsx", ".js", ".jsx", ".json"],
            },
        },
        react: {
            version: "detect",
        },
        "jsx-a11y": {
            // Map perseus components to their corresponding DOM elements. This
            // helps eslint-plugin-jsx-a11y understand what the underlying
            // elements are. For more details, see
            // https://github.com/jsx-eslint/eslint-plugin-jsx-a11y?tab=readme-ov-file#component-mapping
            components: {
                NumericInput: "input",
                ScrolllessNumberTextField: "input",
                BlurInput: "input",
                TextInput: "input",
                NumberInput: "input",
                // TypedSingleSelect wraps Wonder Blocks' SingleSelect, whose
                // closest DOM equivalent is a `select`. Mapping it lets
                // jsx-a11y associate labels with the control (see the
                // SingleSelect mapping in @khanacademy/eslint-config/a11y).
                TypedSingleSelect: "select",
            },
        },
    },
    env: {
        "jest/globals": false,
        node: true,
        browser: true,
    },
    globals: {
        // `no-undef` doesn't support `globalThis`, for details see
        // https://github.com/eslint/eslint/issues/15199.
        globalThis: false, // means it isn't writeable
        // from node_modules/@types/react/index.d.ts
        JSX: false,
        // from lib.dom.d.t.s
        ClientRect: false,
        WindowProxy: false,
        // from types/utility.d.ts
        Empty: false,
        SpreadType: false,
    },
    overrides: [
        ...noSelfPackageImports,
        {
            files: [
                "*.cypress.tsx",
                "*.cypress.ts",
                "*.test.ts",
                "*.test.tsx",
                "*.testdata.ts",
                "*.typetest.ts",
                "*.typetest.tsx",
                "*.stories.ts",
                "*.stories.tsx",
                "**/__testutils__/**",
                "**/__stories__/**",
                "**/__docs__/**",
            ],
            rules: {
                "max-lines": "off",
                "import/no-extraneous-dependencies": "off",
                "import/no-relative-packages": "off",
            },
        },
        {
            files: [
                "*.cypress.ts",
                "*.cypress.tsx",
                "config/cypress/support.ts",
                "packages/perseus/src/testing/render-question-with-cypress.tsx",
            ],
            extends: ["plugin:cypress/recommended"],
            rules: {
                "cypress/assertion-before-screenshot": "error",
                "cypress/no-async-before": "error",
                "cypress/no-debug": "error",
                "cypress/no-force": "error",
                "cypress/no-pause": "error",
            },
        },
        {
            // Storybook has an API for interaction tests that is similar
            // to React Testing Library's `screen`, which causes the
            // `testing-library/prefer-screen-queries` rule to trigger.
            // Disabling this rule for stories files so that we can use
            // `canvas.getBy...` without having to suppress this everywhere.
            files: ["**/*.stories.@(js|jsx|ts|tsx)"],
            rules: {
                "testing-library/prefer-screen-queries": "off",
            },
        },
        {
            files: [
                "config/**",
                "utils/**",
                "packages/*/src/testing/*",
                "typedoc.config.cjs",
            ],
            rules: {
                "@typescript-eslint/no-require-imports": "off",
                "import/no-commonjs": "off",
                "import/no-extraneous-dependencies": "off",
                "import/no-relative-packages": "off",
                "no-console": "off",
                "testing-library/no-debugging-utils": "off",
            },
        },
        {
            files: ["score-*.ts"],
            rules: {
                "no-restricted-syntax": [
                    "error",
                    {
                        selector:
                            "ImportDeclaration > ImportSpecifier[local.name='APIOptions']",
                        message:
                            "APIOptions is not available and should not be imported in scoring functions.",
                    },
                    {
                        selector: "ImportDeclaration[source.value='react']",
                        message:
                            "React is not available and should not be imported in scoring functions.",
                    },
                ],
            },
        },
        {
            /**
             * .typetest.ts files are used to do "type testing" :mindblown:
             * It is common practice in these files to declare variables and
             * expressions that are never used.
             */
            files: ["*.typetest.ts"],
            rules: {
                "@typescript-eslint/no-unused-vars": "off",
                "@typescript-eslint/no-unused-expressions": "off",
            },
        },
        {
            files: ["*.ts", "*.tsx"],
            parser: "@typescript-eslint/parser",
            parserOptions: {
                project: ["tsconfig.json", "config/cypress/tsconfig.json"],
            },
            rules: {
                "@typescript-eslint/strict-boolean-expressions": [
                    "error",
                    {
                        allowNumber: false, // Prevents using numbers as booleans (if (0))
                        allowAny: true, // Allow any type to bypass the rule
                        allowNullableBoolean: true, // Allow nullable booleans in conditionals (e.g., `null` or `undefined`)
                        allowNullableString: true,
                        allowNullableNumber: true,
                    },
                ],
            },
            excludedFiles: ["*.d.ts"],
        },
    ],
    reportUnusedDisableDirectives: true,
    rules: {
        // Enable the RTL rule now. Other wonder-blocks/strict rules stay off
        // so this PR stays scoped to logical CSS properties.
        "@khanacademy/wonder-blocks/require-logical-properties-for-rtl":
            "error",
        "@khanacademy/wonder-blocks/no-hardcoded-color": "off",
        "@khanacademy/wonder-blocks/no-raw-button": "off",
        "@khanacademy/wonder-blocks/no-invalid-bodytext-children": "off",
        "@khanacademy/wonder-blocks/no-custom-tab-role": "off",
        "@khanacademy/wonder-blocks/no-excessive-bodytext-children": "off",
        "@khanacademy/wonder-blocks/no-invalid-bodytext-parent": "off",
        "new-cap": "off",
        "no-invalid-this": "off", // @typescript-eslint/no-invalid-this supersedes it
        "no-unused-expressions": "off", // @typescript-eslint/no-unused-expression supersedes it
        "object-curly-spacing": "off",
        semi: "off",

        /**
         * Overrides @khanacademy/eslint-config, which exempts any variable
         * named `_` (varsIgnorePattern: "^_*$"). That exemption also covers
         * import bindings, so a dead `import _ from "underscore"` was
         * invisible to the linter
         */
        "@typescript-eslint/no-unused-vars": [
            "error",
            {
                args: "none",
                caughtErrors: "none",
                ignoreRestSiblings: true,
                varsIgnorePattern: "^_\\d+$",
            },
        ],

        "no-alert": "error",

        /**
         * jest
         */
        "jest/no-focused-tests": "error",

        /**
         * jsdoc
         */
        "jsdoc/valid-types": "error",

        /**
         * import
         */
        // "import/no-default-export": "error",
        // "import/no-unresolved": "error",
        "import/no-extraneous-dependencies": "error",
        // NOTE(kevinb): This rule is confused by third-party TypeScript lib defs
        "import/named": "off",
        "import/default": "error",
        "import/namespace": "error",
        "import/no-absolute-path": "error",
        "import/no-self-import": "error",
        "import/no-useless-path-segments": "error",
        "import/no-named-as-default": "error",
        // NOTE(kevinb): This rule is causes issues with some uses of 'prop-types'
        "import/no-named-as-default-member": "off",
        "import/no-commonjs": "error",
        // "import/first": "error",
        "import/no-duplicates": "error",
        "import/order": [
            "error",
            {
                alphabetize: {
                    order: "asc",
                },
                groups: [
                    "builtin",
                    "external",
                    "internal",
                    "parent",
                    "sibling",
                    "type",
                ],
                "newlines-between": "always",
            },
        ],
        "import/newline-after-import": "error",
        "import/no-unassigned-import": [
            "error",
            {
                allow: [
                    "**/*.css",
                    "@testing-library/jest-dom",
                    "@testing-library/jest-dom/extend-expect",
                    "whatwg-fetch",
                ],
            },
        ],
        "import/no-named-default": "error",
        "import/no-relative-packages": "error",
        "import/no-restricted-paths": [
            "error",
            {
                zones: [
                    {
                        target: "./packages/(?!.*test.js).*",
                        from: "utils",
                    },
                    {
                        // Files in parse-perseus-json may not import from the
                        // rest of the codebase — it must stay self-contained.
                        target: "./packages/perseus-core/src/parse-perseus-json/perseus-parsers/**/!(*.typetest).ts",
                        from: "./packages/perseus-core/src",
                        except: ["./parse-perseus-json"],
                    },
                ],
            },
        ],
        "no-restricted-syntax": [
            "error",
            {
                selector:
                    "MemberExpression[property.name='render'][object.name='ReactDOM']",
                message: "DEPRECATED: Use a React Portal instead.",
            },
            ...banImportExtension("js"),
            ...banImportExtension("jsx"),
            ...banImportExtension("ts"),
            ...banImportExtension("tsx"),
            {
                selector: "TSQualifiedName[left.name='React'][right.name='FC']",
                message:
                    "Use of React.FC<Props> is disallowed, use the following alternative: https://khanacademy.atlassian.net/wiki/spaces/ENG/pages/2201682693/TypeScript+for+Flow+Developers#Functional-Components",
            },
            {
                // Ban `expr as Type` casts (TSAsExpression). `as const` is
                // excluded because it's a const assertion — a distinct
                // construct that has no `satisfies` equivalent.
                selector:
                    "TSAsExpression:not([typeAnnotation.typeName.name='const'])",
                message:
                    "Avoid `as` for type casting — it bypasses type checking. Prefer `satisfies` to verify a value matches a type without widening or losing inference. If a cast is truly necessary (e.g., at an unsafe boundary like an external API), disable this rule on the line with a comment explaining why.",
            },
            {
                // Ban the legacy angle-bracket assertion form: `<Type>expr`.
                selector: "TSTypeAssertion",
                message:
                    "Avoid angle-bracket type assertions (`<Type>expr`) — they bypass type checking. Prefer `satisfies` to verify a value matches a type without widening or losing inference.",
            },
        ],
        "no-restricted-properties": [
            "error",
            {
                object: "Math",
                property: "random",
                message:
                    "Use seeded randomness. See: https://khanacademy.atlassian.net/browse/LEMS-3397",
            },
        ],
        "no-restricted-imports": [
            "error",
            {
                paths: restrictedImportPaths,
            },
        ],

        /**
         * monorepo
         */
        "monorepo/no-internal-import": "error",

        /**
         * prettier - disabled in CI. W we run prettier manually here as its
         * faster than through ESLint and covers more types of files than
         * ESLint does.
         *
         * For Prettier, we include all files except those in
         * `.prettierignore`.
         * For ESLint we only consider TS/JS files (see `lint` script in
         * package.json).
         */
        "prettier/prettier": [process.env.CI === "true" ? "off" : "error"],

        /**
         * promise
         */
        // "promise/always-return": "error",
        "promise/no-return-wrap": "error",
        "promise/param-names": "error",
        // "promise/catch-or-return": "error",
        "promise/no-new-statics": "error",
        "promise/no-return-in-finally": "error",

        /**
         * react
         */
        "react/no-string-refs": "off", // on in react/recommended, but we have #legacy-code
        "react/no-find-dom-node": "off", // on in react/recommended, but we have #legacy-code
        // On in react/recommended, but doesn't seem helpful
        // (requires quotes to be escaped to catch developer mistakes when other characters are misplaced)
        "react/no-unescaped-entities": "off",
        // This rule results in false-positives when using some types of React
        // components (such as functional components or hooks). Since
        // TypeScript is already checking that components are only using props
        // defined in the component's `Props` type.
        "react/prop-types": "off",
        "react/sort-comp": [
            "error",
            {
                order: [
                    "type-annotations",
                    "static-variables",
                    "instance-variables",
                    "static-methods",
                    "constructor",
                    "lifecycle",
                    "everything-else",
                    "render",
                ],
            },
        ],

        /**
         * react-hooks
         */
        "react-hooks/rules-of-hooks": "error",
        "react-hooks/exhaustive-deps": "error",

        /**
         * react-native
         */
        "react-native/no-unused-styles": "error",

        /**
         * testing-library
         */
        "testing-library/await-async-queries": "error",
        "testing-library/prefer-user-event": "error",
        "testing-library/prefer-explicit-assert": "error",

        // These rules results in a lot of false positives
        "testing-library/render-result-naming-convention": "off",

        /**
         * typescript
         */
        "@typescript-eslint/no-empty-function": "off",
        "@typescript-eslint/no-invalid-this": "error",
        "@typescript-eslint/no-this-alias": "off",
        "@typescript-eslint/consistent-type-imports": [
            "error",
            {
                prefer: "type-imports",
                fixStyle: "separate-type-imports",
            },
        ],
        "@typescript-eslint/no-restricted-imports": [
            "error",
            "@khanacademy/wonder-blocks-color",
            "@khanacademy/wonder-blocks-spacing",
        ],
    },
};