@boundaries/policies

Evaluation of the dependency policies of @boundaries/eslint-plugin and their messages, without ESLint.

Table of Contents

• Introduction
• Features
• Installation
  • Browser Support
• Quick Start
• Core Concepts
  • Skipped Dependencies
  • Evaluation of the Policies
  • Memoization
• API Reference
• Type Reference
• Contributing
• License

Introduction

@boundaries/policies decides dependencies exactly as the dependencies rule of @boundaries/eslint-plugin does: it describes files and dependencies from their paths, tells whether the rule checks a dependency, evaluates the policies and builds the message that the rule reports.

It takes the settings and the rule options as @boundaries/config normalizes them. The ESLint plugin uses it after reading the AST and resolving the imported modules; a tool without ESLint, such as a playground or an MCP server, can use it to explain the same verdicts.

[!NOTE] This package does not run ESLint, read files, resolve modules or print anything. The host passes the paths of the files, and the resolved path of each dependency when it has one; the problems found while evaluating are returned as diagnostics.

Features

• File and dependency descriptions from paths, through the matcher of @boundaries/elements
• The checks of the dependencies rule that decide whether a dependency is evaluated, with the reason when it is not
• Policy evaluation with the rule's semantics: the last policy that matches decides, disallow takes precedence over allow within a policy, and the default option decides when no policy matches
• The deciding policy and match, for allowed dependencies too
• The messages the plugin reports, default and custom, with Handlebars and legacy ${...} templates
• Runs in Node.js and in browsers, without ESLint

Installation

Install the package, with @boundaries/config to normalize the settings and rule options:

npm install @boundaries/policies @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.

Quick Start

Normalize a config, then describe and evaluate a dependency:

import { normalizeConfig } from "@boundaries/config";
import { describeDependency, evaluateDependency } from "@boundaries/policies";

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

const dependency = describeDependency(settings, {
  from: "/project/src/helpers/format/index.js",
  to: "/project/src/components/atoms/Price/index.js",
  source: "../../components/atoms/Price",
  kind: "value",
  nodeKind: "import",
});

const evaluation = evaluateDependency(
  settings,
  rules.dependencies!.options,
  dependency
);

// {
//   checked: true,
//   allowed: false,
//   policyIndex: null,
//   match: null,
//   message: 'There is no policy allowing dependencies from elements of type "helper" to elements of type "component"',
//   diagnostics: [],
// }

Core Concepts

Skipped Dependencies

The dependencies rule does not evaluate every dependency. getDependencySkipReason returns the first reason that applies, in this order, or null:

It reads only the check* options, so it takes the options as the user wrote them or normalized. evaluateDependency returns { checked: false, reason } when there is a reason.

DEPENDENCY_SKIP_REASONS_MAP holds the reasons as constants, from FROM_IGNORED: "from-ignored" to INTERNAL: "internal", to compare a reason without writing its string.

Evaluation of the Policies

evaluatePolicies merges the from, to and dependency selectors of each policy with each entry of its allow and disallow, and matches the dependency against them:

• The last policy that matches decides.
• Within a policy, allow is not evaluated when disallow matched.
• When no policy matches, the default option decides, and policyIndex and match are null.

When the dependency is not allowed, message is the message the plugin reports: the custom message of the deciding policy, or of the options, rendered with its template, or the default message. The exception is a custom message that fails to render, such as one with invalid Handlebars syntax or an unknown helper: evaluatePolicies throws an error that names the message and the policy that sets it, or the options, with the Handlebars error as its cause.

Memoization

The matcher is memoized by the identity of the normalized settings, and the merged selectors of each policy by the identity of the normalized policy, in WeakMaps. Pass the same normalized objects while the config does not change, and new ones when it does; the old entries are collected with them. Results are shared with the memoization of @boundaries/elements, so they must not be mutated.

API Reference

DependencyDescriptorOptions is the input of @boundaries/elements: from and to are paths (to is the resolved path of the target, absent when nothing resolves it), source is the import specifier as written, kind is value or type, nodeKind is the name of the dependency node (import, export, require, dynamic-import, or the name of an additional dependency node) and specifiers are the named imports or exports. A host without a resolver passes to only for the files it knows: with the default boundaries/flag-as-external setting, an unresolved non-relative source is external, or core for a Node.js built-in.

Type Reference

type DependencySkipReason =
  | "from-ignored"
  | "from-unknown"
  | "to-ignored"
  | "not-local"
  | "unknown-local"
  | "internal";

type DependencySkipOptions = {
  checkAllOrigins?: boolean;
  checkUnknownLocals?: boolean;
  checkInternals?: boolean;
};

type PolicyEvaluation = {
  /** Index in options.policies of the policy that decided, or null when options.default decided */
  policyIndex: number | null;
  /** What the deciding selector matched, or null when options.default decided */
  match: DependencySingleSelectorMatchResult | null;
  /** Problems found while matching, with paths from the root of the options */
  diagnostics: Diagnostic[];
} & (
  | { allowed: true; message?: undefined }
  /** message: the message the plugin reports */
  | { allowed: false; message: string }
);

type DependencyEvaluation =
  | ({ checked: true } & PolicyEvaluation)
  | { checked: false; reason: DependencySkipReason };

The types of the context that custom message templates receive are exported too: CustomMessageTemplateContext, CustomMessageTemplatePolicyContext, CustomMessageTemplatePolicySelectorContext and CustomMessageTemplatePolicyEntitySelectorContext. Diagnostic and the settings and options types are exported by @boundaries/config, and the description and selector types by @boundaries/elements.

Contributing

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

License

MIT, see LICENSE for details.