@lostofthought/eslint-plugin-ban-types-in-stage

An ESLint plugin to prevent the usage of types and values from one programming "stage" in another.

This plugin is primarily intended for use with typed-factorio when developing a Factorio mod with multiple Factorio API stages (settings, prototype, runtime) in the same TypeScript project without seperate tsconfig.json files.

Installation and Setup

1. Install Dependencies

Install ESLint, TypeScript, the TypeScript parser, and the plugin in one command:

pnpm add -D eslint typescript @typescript-eslint/parser @lostofthought/eslint-plugin-ban-types-in-stage

2. Configure ESLint

To get everything working, you need to configure the TypeScript parser and then add the plugin. Here is a complete eslint.config.js example:

// eslint.config.js
import typescriptParser from '@typescript-eslint/parser';
import banTypesInStagePlugin from '@lostofthought/eslint-plugin-ban-types-in-stage';

export default [
  // This first part sets up the parser for typed linting.
  // It must come before any rules that require type information.
  {
    files: ['src/**/*.ts'], // Adjust this glob to match your source files
    languageOptions: {
      parser: typescriptParser,
      parserOptions: {
        project: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },

  // The plugin has pre-built configurations. For Factorio mods, it is recommended
  // to use the 'factorio' config, which assumes this structure:
  // - `src/control/` for runtime files
  // - `src/data/` for prototype files
  // - `src/settings/` for settings files
  //
  // To use it, uncomment this line:
  // ...banTypesInStagePlugin.configs.factorio,

  // For other project structures or for non-Factorio projects, configure the rule manually.
  // First, register the plugin:
  {
    plugins: {
      '@lostofthought/ban-types-in-stage': banTypesInStagePlugin,
    },
  },

  // Then, configure the rule for each "stage" of your project. For example,
  // to prevent backend code from being imported into the frontend:
  {
    // Ban backend code in frontend files
    files: ['src/frontend/**/*.ts'],
    rules: {
      '@lostofthought/ban-types-in-stage/ban': ['error', {
        bannedPaths: ['src/backend'],
        currentStage: 'frontend',
      }],
    },
  },
  {
    // Ban frontend code in backend files
    files: ['src/backend/**/*.ts'],
    rules: {
      '@lostofthought/ban-types-in-stage/ban': ['error', {
        bannedPaths: ['src/frontend'],
        currentStage: 'backend',
      }],
    },
  },
];

When using the factorio config ruleset, you must configure your tsconfig.json to include the types for all Factorio stages. By loading all types, TypeScript becomes aware of all stage-specific definitions, which allows this ESLint plugin to correctly identify and restrict their usage in the appropriate files.

{
  "compilerOptions": {
    "types": [
      "typed-factorio/settings",
      "typed-factorio/prototype",
      "typed-factorio/runtime"
    ]
  },

  "tstl": {
    "buildMode": "library",
    "extension": ".lua",
    "luaTarget": "5.2",
    "noImplicitGlobalVariables": true,
    "noImplicitSelf": true,
    "noHeader": true,
    "lua51AllowTryCatchInAsyncAwait": false,
    "luaLibImport": "require-minimal",
    "sourceMapTraceback": true,
    "luaPlugins": [],
    "tstlVerbose": true,
    "noResolvePaths": []
  },
  
  "include": [
    "./src/**/*.ts",
    "./src/**/*.tsx"
  ]
}

Rules

This plugin exports one rule:

• @lostofthought/ban-types-in-stage/ban: Disallow using types/values that are defined in specific files for a given stage.

Contributing

This project uses semantic-release for automated versioning and releases. Please follow the Conventional Commits specification for your commit messages.

License

MIT