@boundaries/config

Normalization and validation of the settings and rule options of @boundaries/eslint-plugin, without ESLint.

Table of Contents

• Introduction
• Features
• Installation
  • Browser Support
• Quick Start
• Core Concepts
  • Diagnostics
  • Diagnostic Paths
  • Normalized Values
• Usage
  • Normalizing a Config
  • Normalizing Settings
  • Validating Rule Options
  • Normalizing the Dependencies Rule Options
  • Getting the Schema of the Rule Options
• API Reference
  • Functions
  • Type Guards
  • Docs Links
  • Constants
• Type Reference
  • Result Types
  • Normalized Types
  • Settings and Rule Options Types
• Contributing
• License

Introduction

@boundaries/config reads what a user writes in the boundaries/* settings and in the rule options of @boundaries/eslint-plugin: it applies their defaults, converts their legacy forms, leaves out the invalid entries and returns every problem as a diagnostic, with the path of the entry that causes it.

The ESLint plugin uses it and prints the diagnostics as warnings. A tool without ESLint, such as an editor or a playground, can use it to show the same problems in its own interface.

[!NOTE] This package does not run ESLint, read files or print anything. It receives the config objects as values and returns the normalized values and their problems; showing the problems is up to the host.

Features

• Settings normalization — defaults applied, legacy settings converted and invalid entries left out
• Rule options validation against the JSON schema of each rule, as ESLint validates them
• Policy checks — unrecognized selector shapes and deprecated syntax in the policies of the rules
• Diagnostics with a level, the texts the ESLint plugin prints and the path of each affected entry
• Pure functions — results are computed on every call and the input is never mutated
• Runs in Node.js and in browsers, without ESLint

Installation

Install the package via npm:

npm install @boundaries/config

Browser Support

The package does not depend on ESLint or Node.js, so it also runs in browsers. Bundlers that build for browsers, such as webpack, Vite or esbuild, select its browser build through the browser condition of its exports field, and that build needs no polyfills of Node.js modules or globals like process.

The package never reads environment variables or the working directory: the host resolves the root path of the project and passes it as the rootPath option.

Quick Start

Normalize the boundaries part of an ESLint config and get its problems:

import { normalizeConfig } from "@boundaries/config";

const { value, diagnostics } = normalizeConfig({
  settings: {
    "boundaries/elements": [
      { type: "helper", pattern: "helpers/*" },
      { pattern: "components/*" },
    ],
  },
  rules: {
    "boundaries/dependencies": [
      2,
      {
        default: "disallow",
        policies: [
          {
            from: { element: { type: "component" } },
            allow: { to: { element: { type: "helper" } } },
          },
        ],
      },
    ],
  },
});

// value.settings.elementDescriptors: the valid element descriptors, without the second one
// value.rules.dependencies.severity: "error"
// value.rules.dependencies.options.policies: the policies with their selectors normalized
// diagnostics:
// [
//   {
//     level: "warning",
//     title: "Some element descriptors are invalid and will be ignored.",
//     detail: 'Invalid descriptors:\n[{"match":"folder","pattern":"components/*"}].\nMore info: https://www.jsboundaries.dev/docs/settings/',
//     paths: [["settings", "boundaries/elements", 1]],
//   },
// ]

Core Concepts

Diagnostics

Functions never print or throw because of a problem in their input. They return each problem as a Diagnostic:

{
  level: "warning",
  title: "Please provide a valid value in 'boundaries/cache' setting.",
  detail: "The value should be a boolean. More info: https://www.jsboundaries.dev/docs/settings/",
  paths: [["boundaries/cache"]],
}

• level: how the input is treated.
  • "error": the input is rejected, as ESLint rejects options that fail the rule schema.
  • "warning": the input is ignored or has no effect.
  • "deprecation": the input uses a legacy syntax that still works.
• title and detail: the texts that the ESLint plugin prints. detail is optional, and it usually ends with a link to the docs.
• paths: one path per affected entry.

A problem found in several entries is returned once, with the paths of all of them, and the diagnostics come in the order the ESLint plugin prints them.

Diagnostic Paths

A path is the list of object keys and array indexes that leads to the affected entry, from the root of the input of the function that returns it. An empty path, [], means the whole input.

A host can use the paths to point at the entry in its own interface, such as highlighting it in an editor.

Normalized Values

normalizeConfig and normalizeSettings return a ConfigResult, { value, diagnostics }. The value is always set, whatever the input: missing settings get their defaults, legacy forms are converted and invalid entries are left out, so a host can use it even when there are diagnostics.

Usage

Normalizing a Config

normalizeConfig takes the boundaries part of an ESLint config object, { settings, rules }. It normalizes the settings with normalizeSettings, and validates each rule entry of the plugin as ESLint validates it, and then as the plugin does:

The severity can be written alone, "warn", or as the first item of an array, ["warn", { ... }]. The rules are keyed by short name in value.rules, and the options of the dependencies rule, and of the deprecated element-types rule, are normalized with normalizeDependenciesRuleOptions.

import { normalizeConfig } from "@boundaries/config";

const { value, diagnostics } = normalizeConfig({
  rules: {
    "boundaries/dependencies": ["error", { default: "maybe" }],
    "boundaries/unknown-rule": "warn",
    "boundaries/no-private": "on",
    "import/no-cycle": 2,
  },
});

// value.rules: {}
// diagnostics:
// [
//   {
//     level: "warning",
//     title: "Please provide element descriptors using the 'boundaries/elements' setting, or file descriptors using the 'boundaries/files' setting.",
//     detail: "More info: https://www.jsboundaries.dev/docs/settings/",
//     paths: [["settings"]],
//   },
//   {
//     level: "error",
//     title: "[boundaries/dependencies] Invalid rule options.",
//     detail: 'Value "maybe" should be equal to one of the allowed values.\nMore info: https://www.jsboundaries.dev/docs/rules/dependencies/',
//     paths: [["rules", "boundaries/dependencies", 1, "default"]],
//   },
//   {
//     level: "error",
//     title: 'Key "rules": Key "boundaries/unknown-rule": Could not find "unknown-rule" in plugin "boundaries".',
//     paths: [["rules", "boundaries/unknown-rule"]],
//   },
//   {
//     level: "error",
//     title: 'Key "rules": Key "boundaries/no-private": Expected severity of "off", 0, "warn", 1, "error", or 2.',
//     paths: [["rules", "boundaries/no-private"]],
//   },
// ]

When the plugin is registered with another name in the ESLint config, pass it as pluginName. Only the rules with that prefix are read:

const { value } = normalizeConfig(
  {
    settings: { "boundaries/elements": [{ type: "app", pattern: "app/*" }] },
    rules: { "arch/no-private": 1 },
  },
  { pluginName: "arch" }
);

// value.rules: { "no-private": { severity: "warn", options: undefined } }

[!NOTE] The settings keep the boundaries/ prefix whatever the plugin name is, as the ESLint plugin reads them.

Normalizing Settings

normalizeSettings takes the settings object of an ESLint config and reads only its boundaries/* keys. It applies the default of each missing setting, converts the legacy settings, such as boundaries/types or boundaries/elements-single-type, into their current form and leaves out the invalid entries. The settings normalized reference lists each property and its default.

import { normalizeSettings } from "@boundaries/config";

const { value, diagnostics } = normalizeSettings(
  {
    "boundaries/elements": [{ type: "component", pattern: "components/*" }],
    "boundaries/ignore": "**/*.spec.js",
    "boundaries/cache": "yes",
  },
  { rootPath: "/project" }
);

// value.ignorePaths: ["**/*.spec.js"]
// value.cache: true
// value.rootPath: "/project"
// diagnostics:
// [
//   {
//     level: "warning",
//     title: "Please provide a valid value in 'boundaries/cache' setting.",
//     detail: "The value should be a boolean. More info: https://www.jsboundaries.dev/docs/settings/",
//     paths: [["boundaries/cache"]],
//   },
// ]

The rootPath option is the root path of the project, already resolved by the host. The ESLint plugin resolves it from the boundaries/root-path setting, the ESLINT_PLUGIN_BOUNDARIES_ROOT_PATH environment variable and the working directory. Without the option, the normalized rootPath is the boundaries/root-path setting as written.

[!NOTE] When the boundaries/legacy-warnings setting is false, the legacy syntax is not reported: neither in the settings nor, through normalizeConfig, in the rule options.

Validating Rule Options

validateRuleOptions validates the options object of a single rule entry, the item after the severity. It validates it against the rule schema, as ESLint does, and then, for the rules with policies, it checks the shape of their selectors and, when legacyWarnings is true, their deprecated syntax.

import { validateRuleOptions } from "@boundaries/config";

const diagnostics = validateRuleOptions(
  "boundaries/dependencies",
  {
    default: "disallow",
    policies: [{ from: "component", allow: "helper" }],
  },
  { legacyWarnings: true }
);

// [
//   {
//     level: "deprecation",
//     title: "[boundaries/dependencies] Detected legacy string element selectors in 1 policy at indices: 0.",
//     detail: 'Replace "your-type" with an entity selector, e.g. { element: { type: "your-type" } }. More info: https://www.jsboundaries.dev/docs/releases/migration-guides/v5-to-v6/#object-based-elements-selector-syntax',
//     paths: [["policies", 0]],
//   },
//   {
//     level: "deprecation",
//     title: '[boundaries/dependencies] Detected "allow"/"disallow" entries without a "from"/"to" wrapper in 1 policy at indices: 0.',
//     detail: 'Use allow: [{ to: { element: { type: "your-type" } } }] or [{ from: ... }] instead of a bare element selector. More info: https://www.jsboundaries.dev/docs/releases/migration-guides/v5-to-v6/#to-property-in-allowdisallow-rules-is-now-required',
//     paths: [["policies", 0]],
//   },
// ]

When the options fail the rule schema, the schema error is the only diagnostic, because ESLint never runs a rule whose options fail it. A host that already runs ESLint, which validates the schema itself, passes schema: false to skip it:

validateRuleOptions("boundaries/dependencies", { default: "maybe" }, { legacyWarnings: true });
// [{ level: "error", title: "[boundaries/dependencies] Invalid rule options.", ... paths: [["default"]] }]

validateRuleOptions("boundaries/dependencies", { default: "maybe" }, { legacyWarnings: true, schema: false });
// []

[!NOTE] The rule name always has the boundaries/ prefix, whatever name the plugin is registered with in the ESLint config.

Normalizing the Dependencies Rule Options

normalizeDependenciesRuleOptions applies the defaults of the options of the dependencies rule and normalizes the selectors of their policies, so a host can match them with @boundaries/elements. It assumes options that passed the rule schema and reports no problem: validate them first with validateRuleOptions.

import { normalizeDependenciesRuleOptions } from "@boundaries/config";

const options = normalizeDependenciesRuleOptions({
  policies: [
    {
      from: { element: { type: "component" } },
      allow: { to: { element: { type: "helper" } } },
    },
  ],
});

// {
//   default: "disallow",
//   message: undefined,
//   policies: [
//     {
//       from: [{ element: [{ type: "component" }] }],
//       allow: [{ to: [{ element: [{ type: "helper" }] }] }],
//       ...
//     },
//   ],
//   checkAllOrigins: false,
//   checkUnknownLocals: false,
//   checkInternals: false,
// }

[!WARNING] The normalized selectors are shared with the memoization of @boundaries/elements. Do not mutate them.

Getting the Schema of the Rule Options

getRuleOptionsSchema returns the JSON schema of the options of a rule, as the ESLint plugin declares it in the rule meta.schema: an array with the schema of each option, empty when the rule takes no options.

import { getRuleOptionsSchema } from "@boundaries/config";

getRuleOptionsSchema("boundaries/no-private");
// [
//   {
//     type: "object",
//     properties: {
//       allowUncles: { type: "boolean" },
//       message: { type: "string" },
//     },
//     additionalProperties: false,
//   },
// ]

getRuleOptionsSchema("boundaries/no-unknown-files");
// []

[!WARNING] The returned schemas are shared between calls. Do not mutate them.

API Reference

Functions

normalizeConfig

Normalizes the boundaries part of an ESLint config, { settings, rules }. See Normalizing a Config.

• Parameters:
  • config: unknown — The config object. Its settings and rules are optional; any other key is ignored.
  • options: NormalizeConfigOptions — Optional.
    • pluginName: string — Optional. The prefix of the rule names in rules. Default "boundaries".
    • rootPath: string — Optional. The root path of the project, already resolved by the host. Without it, the normalized rootPath is the boundaries/root-path setting as written.
• Returns: ConfigResult<ConfigNormalized> — The normalized config and the problems found, with paths from the root of the config object.

const { value, diagnostics } = normalizeConfig(config, { rootPath: "/project" });

normalizeSettings

Normalizes the boundaries/* settings. See Normalizing Settings.

• Parameters:
  • settings: Record<string, unknown> | undefined — The settings object of an ESLint config. Only its boundaries/* keys are read.
  • options: NormalizeSettingsOptions — Optional.
    • rootPath: string — Optional. The root path of the project, already resolved by the host. Without it, the normalized rootPath is the boundaries/root-path setting as written.
• Returns: ConfigResult<SettingsNormalized> — The normalized settings and the problems found, with paths from the root of the settings object.

const { value, diagnostics } = normalizeSettings(config.settings, { rootPath: "/project" });

validateRuleOptions

Validates the options of a rule entry. See Validating Rule Options.

• Parameters:
  • ruleName: RuleName — The name of the rule, with the boundaries/ prefix, such as "boundaries/dependencies".
  • options: unknown — The options object of the rule entry, or undefined when the entry has no options.
  • validation: RuleOptionsValidation — What to validate.
    • legacyWarnings: boolean — Whether to report the deprecated syntax of the policies, as the boundaries/legacy-warnings setting does.
    • schema: boolean — Optional. Whether to validate the options against the rule schema, as ESLint does with the rule meta.schema. Default true; a host that already runs ESLint passes false.
• Returns: Diagnostic[] — The problems found, with paths from the root of the options object. When the schema validation fails, only its error.

const diagnostics = validateRuleOptions("boundaries/dependencies", options, {
  legacyWarnings: true,
});

normalizeDependenciesRuleOptions

Applies the defaults of the options of the dependencies rule and normalizes the selectors of their policies. See Normalizing the Dependencies Rule Options.

• Parameters:
  • options: DependenciesRuleOptions | undefined — The options of the dependencies rule, or of the deprecated element-types rule, already validated against the rule schema.
• Returns: DependenciesRuleOptionsNormalized — The options with their defaults applied. The policies come from policies, or from the deprecated rules when policies is not set, and each one keeps its index.

const options = normalizeDependenciesRuleOptions({ default: "allow", policies: [] });

getRuleOptionsSchema

Returns the JSON schema of the options of a rule. See Getting the Schema of the Rule Options.

• Parameters:
  • ruleName: RuleName — The name of the rule, with the boundaries/ prefix.
• Returns: JsonSchema[] — The schema of each option of the rule, empty when the rule takes no options.

const schema = getRuleOptionsSchema("boundaries/dependencies");

Type Guards

Each one receives a value of type unknown and returns true when the value is of the type.

isRuleName("boundaries/dependencies"); // true
isRuleName("dependencies"); // false
isRuleShortName("dependencies"); // true

Docs Links

Builders of the links to jsboundaries.dev that the diagnostics carry. Every anchor parameter is an optional string, added to the URL as #<anchor>, and every function returns a string.

path, versionFrom and versionTo are strings, and ruleName is a RuleName.

ruleDocsUrl("boundaries/no-unknown"); // "https://www.jsboundaries.dev/docs/rules/no-unknown-dependencies/"
moreInfoSettingsLink(); // "More info: https://www.jsboundaries.dev/docs/settings/"

Constants

The values of the maps are also exported one by one, such as DEPENDENCIES, DEPENDENCY_NODE_IMPORT, RULE_EFFECT_ALLOW or NO_UNKNOWN_DEPENDENCIES_REQUIRE_ANY.

Type Reference

Result Types

ConfigResult

Returned by normalizeConfig and normalizeSettings, as ConfigResult<T>.

Diagnostic

A problem found in the input. See Diagnostics.

Normalized Types

ConfigNormalized

The value returned by normalizeConfig.

RuleEntryNormalized

A rule entry of ConfigNormalized, as RuleEntryNormalized<Name>.

SettingsNormalized

The value returned by normalizeSettings, and the settings of ConfigNormalized.

ElementDescriptors, FileDescriptors and FlagAsExternalOptions are types of @boundaries/elements.

DebugSettingNormalized

DependenciesRuleOptionsNormalized

Returned by normalizeDependenciesRuleOptions, and the options of the dependencies and element-types entries of ConfigNormalized.

DependenciesPolicyNormalized

The selector types are types of @boundaries/elements, which describes them in its selector reference.

Settings and Rule Options Types

The package exports the types of what a user writes, so a host can type its own config objects. The main ones are:

The no-ignored-dependencies, no-ignored and no-unknown-files rules take no options. DependenciesRule, DependenciesRuleNormalized, EntryPointRule, ExternalRule, ExternalLibrarySelectors, RulePolicy and AliasSetting are deprecated.

Contributing

Contributors are welcome. Please read the contributing guidelines and code of conduct.

License

MIT, see LICENSE for details.