eslint.config.js

import path from "node:path";
import { includeIgnoreFile } from "@eslint/compat";
import tseslint from "typescript-eslint";
import prettierConfigRules from "eslint-config-prettier/flat";
import prettierPlugin from "eslint-plugin-prettier";
import importPlugin from "eslint-plugin-import";
import tsdoc from "eslint-plugin-tsdoc";
import js from "@eslint/js";
import globals from "globals";

const gitignorePath = path.resolve(".", ".gitignore");

const javascriptConfig = [
  js.configs.recommended,
  {
    name: "javascript/node-globals",
    files: ["**/*.js", "**/*.ts"],
    languageOptions: {
      globals: {
        ...globals.node,
      },
    },
  },
];
const typescriptConfig = [
  // typescript-eslint recommended (registers the parser + plugin)
  ...tseslint.configs.recommended,
  {
    name: "typescript/parser-options",
    files: ["**/*.ts", "**/*.tsx"],
    languageOptions: {
      parserOptions: {
        projectService: false,
        project: ["./tsconfig.json"],
      },
    },
  },
  {
    name: "typescript/custom-rules",
    files: ["**/*.ts", "**/*.tsx"],
    rules: {
      "@typescript-eslint/require-await": "error",
      // Delegated to TypeScript's `noUnusedLocals` / `noUnusedParameters`
      // (set in tsconfig.json) — TS understands JSDoc `{@link}` references,
      // typescript-eslint's no-unused-vars does not.
      "@typescript-eslint/no-unused-vars": "off",
      "no-unused-vars": "off",
      "no-fallthrough": "off",
      // `any` is used deliberately at dynamic boundaries — XDR decoding,
      // JSON-RPC payloads, and Horizon response shaping — across ~125 sites,
      // too many to annotate individually. Tightening these is tracked as
      // separate, incremental work.
      "@typescript-eslint/no-explicit-any": "off",
      // `namespace` declarations are part of the published public API
      // (e.g. Horizon, rpc `Api`, stellartoml), not an organizational crutch.
      "@typescript-eslint/no-namespace": "off",
    },
  },
];
const prettierConfig = [
  // Prettier Plugin and Config
  {
    name: "prettier/config",
    plugins: {
      prettier: prettierPlugin,
    },
    rules: {
      ...prettierConfigRules.rules,
      "prettier/prettier": ["error"],
    },
  },
];

const tsdocConfig = [
  {
    name: "tsdoc/syntax",
    files: ["**/*.ts"],
    plugins: { tsdoc },
    rules: { "tsdoc/syntax": "warn" },
  },
];

const testConfig = [
  {
    name: "test/typescript",
    files: ["test/**/*.ts", "test/**/*.tsx", "test/**/*.js"],
    languageOptions: {
      parserOptions: {
        project: "./test/tsconfig.json",
      },
    },
    rules: {
      "no-unused-vars": 0,
      radix: 0,
      "@typescript-eslint/no-throw-literal": 0,
    },
  },
];

// Guide snippets (examples/guides/*.ts) are standalone programs embedded into
// docs/guides/*.md, not library code. They live outside tsconfig.json's `src`
// include, so point type-aware lint at their own project.
const examplesConfig = [
  {
    name: "examples/typescript",
    files: ["examples/**/*.ts"],
    languageOptions: {
      parserOptions: {
        project: "./examples/tsconfig.json",
      },
    },
    rules: {
      // Snippets read as documentation: they log, and they evaluate
      // expressions like `result.hash` to show what a response carries.
      "no-console": "off",
      "@typescript-eslint/no-unused-expressions": "off",
    },
  },
];

const scriptsConfig = [
  {
    name: "scripts/typescript",
    files: ["scripts/**/*.ts"],
    languageOptions: {
      parserOptions: {
        project: "./scripts/tsconfig.json",
      },
    },
  },
];

// The base XDR/SDK module preserves a public API shape (namespace+const merging,
// XDR-string-literal type aliases, snake_case helpers like `best_r`, leading-_
// internals) and uses a "public API at top, helpers below" file layout. Loosen
// rules that would otherwise force breaking renames or large reorders.
const baseSdkConfig = [
  {
    name: "base/sdk-public-api",
    files: ["src/base/**/*.ts"],
    rules: {
      "@typescript-eslint/no-redeclare": "off",
      "@typescript-eslint/no-use-before-define": [
        "error",
        { functions: false },
      ],
      "@typescript-eslint/naming-convention": "off",
    },
  },
];

// The generated class-XDR layer relies on abstract-base ↔ concrete-subclass
// references that are only safe under class hoisting, and preserves generated
// naming/redeclaration shapes. Loosen the rules that would otherwise flag them.
const xdrGenConfig = [
  {
    name: "src/xdr",
    files: ["src/xdr/**/*.ts"],
    rules: {
      "@typescript-eslint/no-redeclare": "off",
      "@typescript-eslint/naming-convention": "off",
      "@typescript-eslint/no-use-before-define": [
        "error",
        { functions: false },
      ],
    },
  },
];

// scripts/build-docs.ts dispatches a discriminated-union renderer through
// mutually recursive helpers; function-declaration hoisting handles the
// runtime ordering. Match baseSdkConfig's `functions: false` loosening.
//
// The scripts are dev-only docs tooling, never bundled into the published
// package, so importing devDependencies (e.g. github-slugger) is expected —
// override airbnb's default that only allows devDeps in test/build-config
// globs.
const scriptsRulesConfig = [
  {
    name: "scripts/mutual-recursion",
    files: ["scripts/**/*.ts"],
    rules: {
      "@typescript-eslint/no-use-before-define": [
        "error",
        { functions: false },
      ],
      "import/no-extraneous-dependencies": ["error", { devDependencies: true }],
    },
  },
];

const importConfig = [
  {
    name: "import/plugin/config",
    plugins: {
      import: importPlugin,
    },
  },
];
const ignoreFiles = includeIgnoreFile(gitignorePath);
ignoreFiles.ignores.push(
  ...[
    "eslint.config.js",
    "rollup.config.mjs",
    "config/**/*",
    "src/base/generated/**",
    "tools/**",
    // Astro build-time configs — excluded from tsconfig.json (they
    // import the virtual `astro:content` module), so the typescript-
    // eslint parser can't resolve them via the SDK project. Lint
    // coverage from prettier is sufficient for these small configs.
    "src/content.config.ts",
    "astro.config.mjs",
  ],
);
export default [
  // Ignore .gitignore files/folder in eslint
  ignoreFiles,
  // Import Plugin Config
  ...importConfig,
  // JavaScript Config
  ...javascriptConfig,
  // TypeScript Config
  ...typescriptConfig,
  // XDR Gen Config (must come after typescriptConfig to allow overrides)
  ...xdrGenConfig,
  // TSDoc Config
  ...tsdocConfig,
  // Test Config
  ...testConfig,
  // Scripts Config (uses scripts/tsconfig.json for type-aware lint)
  ...scriptsConfig,
  // Examples Config (uses examples/tsconfig.json for type-aware lint)
  ...examplesConfig,
  // Base SDK overrides (must come after typescriptConfig/tsdocConfig)
  ...baseSdkConfig,
  // Scripts overrides (must come after typescriptConfig/scriptsConfig)
  ...scriptsRulesConfig,
  // Prettier Config
  ...prettierConfig,
];