Configuration file format

[illright]

The current configuration file needs to be revised. This discussion is for proposals for a new config file format.

Requirements:

• should support turning rules on/off/warn
• should allow passing options to individual rules
• should allow including/excluding parts of the project from being checked by particular rules
• should support custom rulesets (from packages or locally written)
• should allow passing options to the whole ruleset (to avoid duplication if, for example, an architecture has some parameters that apply to all rules in a ruleset)
• should be typed (type-checking, autocompletion, inline documentation)
• should be easy to learn (reusing conventions, minimal by default)
• should be optional for the happy path (for now, in case of standard FSD; maybe in the future it could support zero-config for other architectures as well)

[illright]

ESLint-style flat config with functions accepting global options

ESLint switched to a new config file format that is an array of objects that are merged. It is very flexible in how each individual rule can be configured, and ESLint is a very popular tool, so reusing its conventions will be good for knowledge transfer.

The proposed format is described in TypeScript as follows:

export type Config = Array<ConfigObject | Plugin>

export interface ConfigObject {
  /** Globs of files to check */
  files?: Array<string>
  /** Globs of files to ignore */
  ignores?: Array<string>
  /** Severity of rules and individual rule options. */
  rules?: {
    [ruleName: string]: Severity | [Severity, Record<string, unknown>]
  }
}

export type Severity = 'off' | 'warn' | 'error'

export interface Plugin {
  meta: {
    name: string
    version: string
  }
  ruleDefinitions: Array<Rule>
}

Example 1. FSD with all rules enabled by default, but excluding a couple of folders

// ./steiger.config.ts
import fsd from '@feature-sliced/steiger-plugin'

export default [
  ...fsd.configs.recommended,
  {
    ignores: ['**/__mocks__/**'],
  },
]

Example 2. FSD with global options

// ./steiger.config.ts
import fsd from '@feature-sliced/steiger-plugin'

export default [
  ...fsd.configs.custom({
    additionalSegmentNames: ['dto'],
    sourceFileExtension: 'js',
  }),
]

Example 3. FSD without certain rules

// ./steiger.config.ts
import fsd from '@feature-sliced/steiger-plugin'

export default [
  ...fsd.configs.recommended,
  {
    rules: {
      'fsd/no-processes': 'off',
      'fsd/no-public-api-sidestep': 'warn',
    },
  },
  {
    files: ['./src/shared/**'],
    rules: {
      'fsd/public-api': 'off',
    },
  },
]

Example 4. Passing options to rules

Plugin creators are encouraged to extend the ConfigObject interface to provide strong types for available rules, as well as rule options. For example:

import type { ConfigObject, Severity } from '@steiger/toolkit'

export interface FSDConfigObject extends ConfigObject {
  rules?: Partial<{
    'fsd/no-processes': Severity
    'fsd/no-public-api-sidestep': Severity
    'fsd/repetitive-naming': Severity
    'fsd/import-locality': Severity
    'fsd/public-api':
      | Severity
      | [
          Severity,
          {
            /** An alternative name/glob for index files. */
            indexFileName: string
          },
        ]
  }>
}

This allows users to get typo protection and autocompletion on their overrides as follows:

// ./steiger.config.ts
import fsd, { type FSDConfigObject } from '@feature-sliced/steiger-plugin'

export default [
  ...fsd.configs.recommended,
  {
    files: ['./src/shared/**'],
    rules: {
      'fsd/public-api': ['warn', { indexFileName: 'index.*' }],
    },
  } satisfies FSDConfigObject,
]

There most likely are ways to autogenerate this object with TypeScript magic, that's a part of DX to explore in the future.

Example 5. Custom ruleset

// ./steiger.config.ts
import type { FSDConfigObject } from '@feature-sliced/steiger-plugin'
import customRules from './architecture/rules'

export default [
  {
    rules: {
      'fsd/repetitive-naming': 'error',
      'fsd/import-locality': 'error',
    },
  } satisfies FSDConfigObject,
  customRules.configs.all,
]

// ./architecture/rules.ts
import { createPlugin, enableAllRules, type ConfigObjectOf } from '@steiger/toolkit'

const superDuperArchitecture = createPlugin({
  meta: {
    name: 'super-duper-architecture',
    version: '1.0.0',
  },
  ruleDefinitions: [
    {
      name: 'sda/no-classes',
      check: (root, options: { forSure: boolean } = { forSure: true }) => {
        /* … */
      },
    },
  ],
})

export type SDAConfigObject = ConfigObjectOf<typeof superDuperArchitecture>

export default {
  configs: {
    all: enableAllRules(superDuperArchitecture, { severity: 'error' }),
  },
}

[EliseyMartynov]

I like that approach, thanks Lev!

Will check function provide some API from Steiger to easily create custom rules?

[illright]

Yes, we will provide a toolkit for writing custom rules quickly. It will be in the form of a separate package that you can install and import utilities from

[noveogroup-amorgunov]

@illright great job

[daniilsapa]

@illright
You've done a very solid job! I look forward to helping you make this happen