eslint-plugin-project-structure

eslint-plugin-project-structure is an ESLint plugin designed to help developers maintain scalable, consistent, and well-structured projects. It allows you to define and enforce your own project framework by automating the review of:

• Folder structure: Enforce where specific files or directories should reside.
• File composition: Define what files should exist within certain directories.
• Naming conventions: Implement advanced naming rules for files and folders.
• Module independence: Create and enforce rules for independent modules.

If you want to test how rules behave before integrating them into your project, you can use the official playground. This is useful for prototyping configurations and understanding rule impact.

https://github.com/Igorkowalski94/eslint-plugin-project-structure-playground#root

When defining the structure in the folderStructure rule, you use Rule objects to specify requirements for files and folders.

• name: The name of the file or folder.
• enforceExistence: A string or array of strings indicating that this item must exist.
• children: An array of nested Rule objects defining the sub-structure.
• NodeType: While not directly in the Rule interface, the rule logic distinguishes between "File" and "Folder" types.

export interface Rule<T extends string = string> {
  ruleId?: T;
  name?: string;
  enforceExistence?: string[] | string;
  children?: Rule<T>[];
}

To use the plugin, you must register the project-structure plugin and use the projectStructureParser as the language parser. The plugin provides rules to enforce architectural constraints such as folder structure, file composition, and module independence.

Note that the plugin requires its own parser to analyze the project structure correctly.

import { projectStructurePlugin, projectStructureParser } from "eslint-plugin-project-structure";

export default [
  {
    files: ["**"],
    languageOptions: { parser: projectStructureParser },
    plugins: {
      "project-structure": projectStructurePlugin,
    },
    rules: {
      "project-structure/folder-structure": ["error", folderStructureConfig],
    },
  },
];

The fileComposition rule is configured using a FileCompositionConfig object. This configuration allows you to define rules for specific files based on patterns, enforce limits on certain types of selectors, and restrict which selectors are allowed in different scopes (file root, file exports, or nested selectors).

Configuration Structure

• projectRoot: (Optional) The root directory of the project.
• regexParameters: (Optional) Parameters for regex processing.
• filesRules: An array of FileRules objects, where each object defines constraints for files matching a specific filePattern.

const config: FileCompositionConfig = {
  projectRoot: './',
  filesRules: [
    {
      filePattern: 'src/**/*.ts',
      // ... rules
    }
  ]
};

Within the filesRules array, you define how files matching a filePattern should be composed. You can enforce strict selector sets, set limits on the number of specific selectors, or define specific rules for how elements are positioned.

FileRules Options

• filePattern: A pattern used to match files.
• allowOnlySpecifiedSelectors: (Optional) A boolean or an AllowOnlySpecifiedSelectors object to restrict which selectors are permitted in fileRoot, fileExport, or nestedSelectors.
• rootSelectorsLimits: (Optional) An array of RootSelectorLimit objects to restrict the count of specific selectors at the file root.
• rules: (Optional) An array of Rule objects defining specific constraints for individual selectors.

Use the allowOnlySpecifiedSelectors option to whitelist specific types of code elements allowed in different parts of a file. You can also provide custom error messages for each selector type.

AllowOnlySpecifiedSelectors Structure

• fileRoot: (Optional) Boolean or CustomErrors for selectors at the top level of the file.
• fileExport: (Optional) Boolean or CustomErrors for selectors that are exported.
• nestedSelectors: (Optional) Boolean or CustomErrors for selectors nested within other structures.
• error: (Optional) A mapping of SelectorType to a custom error message string.

allowOnlySpecifiedSelectors: {
  fileRoot: true,
  fileExport: {
    class: 'Do not export classes from this directory',
    function: 'Use arrow functions instead'
  }
}

The rootSelectorsLimits option allows you to control the quantity of specific selector types allowed at the file's root level.

RootSelectorLimit Structure

• selector: A SelectorType or an array of SelectorTypes.
• limit: A number or an object defining max and/or min values.

rootSelectorsLimits: [
  {
    selector: 'class',
    limit: { max: 2 }
  },
  {
    selector: ['interface', 'type'],
    limit: 5
  }
]

The rules array within FileRules allows for granular control over how specific elements are composed. You can control their position, sorting, and formatting.

Rule Structure

• selector: A SelectorType or a VariableExpression.
• scope: (Optional) The scope to apply the rule to (fileExport, fileRoot, nestedSelectors, or file).
• positionIndex: (Optional) An object specifying the index and optional sorting ('az' or 'none').
• filenamePartsToRemove: (Optional) A string or array of strings to strip from the filename.
• format: (Optional) A string or array of strings defining the expected format.

rules: [
  {
    selector: 'class',
    scope: 'fileExport',
    positionIndex: { index: 0, sorting: 'az' }
  }
]