npm package: @lostofthought/eslint-plugin-ban-types-in-stage
Description: An ESLint plugin to prevent the usage of types and values from one programming "stage" in another.
Author: Ryan "LostOfThought" Wright
Latest version: 1.0.1

# @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](https://github.com/GlassBricks/typed-factorio) when developing a Factorio mod with multiple [Factorio API stages](https://lua-api.factorio.com/latest/) (`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:

```sh
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:

```javascript
// 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.

```jsonc
{
  "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`](./docs/rules/ban.md): 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](https://www.conventionalcommits.org/en/v1.0.0/) specification for your commit messages.

## License

MIT