eslint-plugin-file-boundaries

Enforce multi-dimensional boundaries between files using JSDoc tags.

Philosophy

File hierarchy alone is often insufficient for defining boundaries in a complex codebase because it only allows differentiation along one axis (the folder structure). eslint-plugin-file-boundaries taps into JSDoc annotations to allow multi-dimensional tagging of files, helping you enforce strict architectural layers and subdomain boundaries.

Example of a tagged file:

/**
 * @layer api
 * @subdomain ordering
 */
export const myService = {};

Installation

npm install eslint-plugin-file-boundaries --save-dev

Add it to your eslint.config.js:

const fileBoundaries = require("eslint-plugin-file-boundaries");

module.exports = [
  {
    plugins: {
      "file-boundaries": fileBoundaries,
    },
    rules: {
      "file-boundaries/tagging-rule": ["error", [
        {
          "tag": "layer",
          "mandatory": true,
          "values": ["api", "frontend", "composition-root"]
        },
        {
          "tag": "subdomain",
          "checkPath": "consistent",
          "values": ["ordering", "fulfillment", "inventory"]
        }
      ]],
      "file-boundaries/import-rule": ["error", [
        {
          "conditions": [{"tag": "layer", "value": "frontend"}],
          "shouldOnlyDependOn": [{"tag": "layer", "value": "api"}]
        }
      ]]
    }
  }
];

Rules

tagging-rule

Ensures that files are correctly tagged using JSDoc. The JSDoc block containing the tags must be at the top of the file.

Configuration

An array of objects with the following properties:

• tag: The name of the JSDoc tag (e.g., layer).
• values: An array of allowed values for this tag.
• mandatory (optional, default false): If true, every file must have this tag.
• checkPath (optional, default none):
  • none: Ignore the file path.
  • consistent: If one of the values is present as a substring in the file's path (folder name), the file must have that value for the tag. This is auto-fixable with --fix.
  • strict: Same as consistent, but also requires that one of the values must be present in the path.

import-rule

Enforces boundaries between files based on their tags.

Configuration

An array of boundary definitions:

• conditions: A list of tags and values that the current file must have for this boundary to apply.
• shouldOnlyDependOn: A list of tags and values that the imported files must have. If an import doesn't match any of these, an error is reported.

LLM Compatibility

Using file-level JSDoc tags also helps LLMs understand the architectural context of a file without needing to traverse the entire directory structure.

License

MIT