Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New config structure docs #96

Merged
merged 25 commits into from
Oct 25, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
667a211
Add info about the new config structure, add a migration guide
daniilsapa Sep 2, 2024
18f240e
Add a change log
daniilsapa Sep 2, 2024
a02bbf9
Fix the migration guide
daniilsapa Sep 3, 2024
c90b991
Remove excess parts from README
daniilsapa Sep 3, 2024
f7ed06b
Fix the migration guide
daniilsapa Sep 3, 2024
813998a
Fix paths in examples
daniilsapa Sep 3, 2024
6d3bbbd
Update README.md
daniilsapa Sep 5, 2024
2f0228b
Update README.md
daniilsapa Sep 5, 2024
4cfeef5
Update README.md
daniilsapa Sep 5, 2024
35e88bc
Merge branch 'master' into feature/new-config-docs
daniilsapa Oct 5, 2024
36af9c6
Add info on global ignores and glob matching specifics
daniilsapa Oct 5, 2024
8349230
Re-phrase some sentences
daniilsapa Oct 5, 2024
28ac1e3
Fix brace sets in glob examples
daniilsapa Oct 10, 2024
72000de
Reflect changes in the main README
daniilsapa Oct 10, 2024
cb3299f
Update README.md
daniilsapa Oct 22, 2024
8904f53
Add a simple example to the beginning of the Example section
daniilsapa Oct 22, 2024
62a03da
Simplify the Example section
daniilsapa Oct 22, 2024
7bd6730
Fix the complex config example and hide it under a spoiler
daniilsapa Oct 22, 2024
545766c
Update MIGRATION_GUIDE.md
daniilsapa Oct 22, 2024
b952267
Button up the docs
daniilsapa Oct 22, 2024
35c1875
Move the Glob matching section to config examples doc
daniilsapa Oct 22, 2024
17da9b5
Reflect the changes in README.md inside packages/steiger
daniilsapa Oct 22, 2024
fd80f66
Merge branch 'feature/new-config-docs' of https://github.com/daniilsa…
daniilsapa Oct 22, 2024
e075e91
Fix imports in the examples
daniilsapa Oct 24, 2024
898ae07
Make some minor fixes to examples
illright Oct 25, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/little-zebras-pay.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'steiger': minor
---

Add documentation about the new config structure
118 changes: 118 additions & 0 deletions CONFIG_EXAMPLES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
# Examples

## Glob matching

All globs are matched only against files, folder severities are computed based on the files inside them. The formula is simple: the folder severity is the highest severity of files inside it (from highest to lowest: error, warn, off).

**Glob examples**:

- `./src/shared/**` - matches all files in the `shared` folder and its subfolders
- `./src/shared/*` - matches all files that are direct children of the `shared` folder
- `./src/shared` - based on the fact that globs are matched against files, this one matches only `shared` file (without an extension) inside the `src` folder
- `**/__mocks__/**` - matches all files in all `__mocks__` folders throughout the project
- `**/*.{test,spec}.{ts,tsx}` - matches all test files in the project

## Example 1. Default case

```javascript
// ./steiger.config.ts
import fsd from '@feature-sliced/steiger-plugin'
import { defineConfig } from 'steiger'

export default defineConfig([...fsd.configs.recommended])
```

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

```javascript
import fsd from '@feature-sliced/steiger-plugin'
import { defineConfig } from 'steiger'

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

## Example 3. FSD without certain rules

```javascript
import fsd from '@feature-sliced/steiger-plugin'
import { defineConfig } from 'steiger'

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

## Example 4. Disabling a rule for a specific folder

```javascript
import fsd from '@feature-sliced/steiger-plugin'
import { defineConfig } from 'steiger'

export default defineConfig([
...fsd.configs.recommended,
{
files: ['./src/shared/**'],
rules: {
'fsd/no-public-api': 'off',
},
},
])
```

## Example 5. Using ignores along with files

```javascript
import fsd from '@feature-sliced/steiger-plugin'
import { defineConfig } from 'steiger'

export default defineConfig([
...fsd.configs.recommended,
{
files: ['./src/shared/**'],
ignores: ['./src/shared/lib/**', './src/shared/ui/**'],
rules: {
'fsd/no-public-api': 'off', // Disable the rule for the shared folder, but not for the lib and ui folders
},
},
])
```

## Example 6. Setting rule options

```javascript
import fsd from '@feature-sliced/steiger-plugin'
import { defineConfig } from 'steiger'

export default defineConfig([
...fsd.configs.recommended,
{
rules: {
'fsd/no-public-api': ['warn', { someOptions: true }],
},
},
{
files: ['./src/shared/**'],
rules: {
'fsd/no-public-api': 'error',
// 'fsd/no-public-api': ['error', { someOptions: false }], // Would throw an error as you can't override the options
},
},
])
```
89 changes: 89 additions & 0 deletions MIGRATION_GUIDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
# Migration guide

## From 0.4.0 to 0.5.0

**Step 1**: First of all you need to make sure you upgraded Steiger package to version 0.5.0 or higher.

**Step 2**: You need to install `@feature-sliced/steiger-plugin` package (that contains all FSD rules to run checks in your project). Run one of the following commands based on the package manager you use.

**pnpm**:

```shell
pnpm add -D @feature-sliced/steiger-plugin
```

**yarn**:

```shell
yarn add -D @feature-sliced/steiger-plugin
```

**npm**:

```shell
npm i -D @feature-sliced/steiger-plugin
```

**Step 3**: The final step. You need to bring your `steiger.config.js` file to the new configuration format. You can do that automatically by running one of the following commands. (Alter the command before running if your config file has an extension different from `.js`)

Here is an example of the transformation that will be applied to your config:

<table><thead><tr>
<th>Before</th>
<th>After</th>
</tr></thead><tbody><tr><td>

```ts
// steiger.config.ts
import { defineConfig } from 'steiger'

export default defineConfig({
rules: {
'public-api': 'off',
'ambiguous-slice-names': 'off',
'no-processes': 'off',
},
})
```

</td><td>

```ts
// steiger.config.ts
import { defineConfig } from 'steiger'
import fsd from '@feature-sliced/steiger-plugin'

export default defineConfig([
...fsd.configs.recommended,
{
rules: {
'fsd/public-api': 'off',
'fsd/ambiguous-slice-names': 'off',
'fsd/no-processes': 'off',
},
},
])
```

</td></tr></tbody></table>

> [!NOTE]
> The codemod will probably get the formatting wrong, so don't forget to check the file yourself after migration.

**pnpm**:

```shell
pnpx jscodeshift -t https://raw.githubusercontent.com/feature-sliced/steiger/master/packages/steiger/migrations/convert-config-to-flat.js steiger.config.js
```

**yarn**:

```shell
yarn dlx jscodeshift -t https://raw.githubusercontent.com/feature-sliced/steiger/master/packages/steiger/migrations/convert-config-to-flat.js steiger.config.js
```

**npm**:

```shell
npx jscodeshift -t https://raw.githubusercontent.com/feature-sliced/steiger/master/packages/steiger/migrations/convert-config-to-flat.js steiger.config.js
```
85 changes: 72 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,19 +7,22 @@ Universal file structure and project architecture linter.
> [!NOTE]
> The project is in beta and in active development. Some APIs may change.

# Features
> [!NOTE]
> Version 0.5.0 introduced a new config file format. We have a codemod to automatically update your config, see the [migration guide](./MIGRATION_GUIDE.md).

## Features

- Built-in set of rules to validate adherence to [Feature-Sliced Design](https://feature-sliced.design/)
- Watch mode
- Rule configurability

# Installation
## Installation

```bash
npm i -D steiger
```

# Usage
## Usage

```bash
npx steiger ./src
Expand All @@ -31,23 +34,79 @@ To run in watch mode, add `-w`/`--watch` to the command:
npx steiger ./src --watch
```

# Configuration
## Configuration

Steiger is zero-config! If you don't want to disable certain rules, you can safely skip this section.

Steiger is configurable via `cosmiconfig`. That means that you can create a `steiger.config.ts` or `steiger.config.js` file in the root of your project to configure the rules. Import `{ defineConfig } from "steiger"` to get autocompletion.
daniilsapa marked this conversation as resolved.
Show resolved Hide resolved

```ts
import { defineConfig } from 'steiger'
The config file shape is highly inspired by ESLint's config file, so if you have configured ESLint before, you'll find it easy to configure Steiger.

export default defineConfig({
rules: {
'public-api': 'off',
### Example

```javascript
// ./steiger.config.js
import { defineConfig } from 'steiger'
import fsd from '@feature-sliced/steiger-plugin'

export default defineConfig([
...fsd.configs.recommended,
{
// disable the `public-api` rule for files in the Shared layer
files: ['./src/shared/**'],
rules: {
'fsd/public-api': 'off',
},
},
})
])
```

# Rules
> [!TIP]
> If you want Steiger to ignore certain files, add an object like this to the config array:
>
> ```js
> defineConfig([, /* … */ { ignores: ['**/__mocks__/**'] }])
> ```

<details>
<summary>Comprehensive showcase of the config file syntax</summary>

```javascript
// ./steiger.config.ts
import { defineConfig } from 'steiger'
import fsd from '@feature-sliced/steiger-plugin'

export default defineConfig([
...fsd.configs.recommended,
{
// ignore all mock files for all rules
ignores: ['**/__mocks__/**'],
},
{
files: ['./src/shared/**'],
rules: {
// disable public-api rule for files in /shared folder
'fsd/public-api': 'off',
},
},
{
files: ['./src/widgets/**'],
ignores: ['**/discount-offers/**'],
rules: {
// disable no-segmentless-slices rule for all widgets except /discount-offers
'fsd/no-segmentless-slices': 'off',
},
},
])
```
[You can see more examples here](CONFIG_EXAMPLES.md)
</details>

### Migration from 0.4.0

Version 0.5.0 introduced a new config file format. Follow the [instructions](MIGRATION_GUIDE.md) to migrate your config file.

## Rules

Currently, Steiger is not extendable with more rules, though that will change in the near future. The built-in rules check for the project's adherence to [Feature-Sliced Design](https://feature-sliced.design/).

Expand Down Expand Up @@ -80,12 +139,12 @@ Currently, Steiger is not extendable with more rules, though that will change in
</tbody>
</table>

# Contribution
## Contribution

Feel free to report an issue or open a discussion. Ensure you read our [Code of Conduct](CODE_OF_CONDUCT.md) first though :)

To get started with the codebase, see our [Contributing guide](CONTRIBUTING.md).

# Legal info
## Legal info

Project licensed under [MIT License](LICENSE.md). [Here's what it means](https://choosealicense.com/licenses/mit/)
Loading