@ 边界/ 配置

设置和规则选项的规范化和验证 @boundaries/eslint-plugin没有ESLint.

目录

• 导言
• 特征
• 安装
  • 浏览器支持
• 快速启动
• 核心概念
  • 诊断
  • 诊断路径
  • 正常化值
• 使用量
  • 规范配置
  • 规范设置
  • 验证规则选项
  • 规范依赖规则选项
  • 获取规则选项的外观
• API 参考
  • 职能
  • 类型警卫
  • Docs 链接
  • 常数
• 类型参考
  • 结果类型
  • 普通类型
  • 设置和规则选项类型
• 捐款
• 许可证

导言

@boundaries/config 阅读用户在 boundaries/* 设置和规则选项 @boundaries/eslint-plugin: 它应用他们的默认值,转换其遗留表单, 保留无效的条目, 并返回每个问题作为 诊断,与导致它的入道.

ESLint插件使用并打印出诊断作为警告. 没有ESLint的工具,如编辑器或游乐场,可以使用它来显示自己界面中相同的问题.

[注] 此软件包不运行ESLint,不读取文件或打印任何东西. 它接收配置对象为值并返回已归正的值及其问题;显示问题取决于主机.

特征

• 设置正常化 ——适用默认,转换遗留设置并保留无效条目
• 规则选项验证 由于ESLint验证了规则中的JSON计划
• 政策检查 ——规则政策中未确认的选取者形状和被贬损的语法
• 诊断 有关卡的,ESLint插件打印的文本和每个受影响的条目的路径
• 纯函数 ——每一次通话都计算结果,输入从未变异
• 在节点.js和浏览器中运行,不包含 ESLint

安装

通过 npm 安装软件包 :

npm install @boundaries/config

浏览器支持

该软件包不依赖于ESLint或Node.js,因此它也在浏览器中运行. 为浏览器所构建的 Bundlers, 如 Webpack, Vite 或 esbuild , 选择它的浏览器通过 browser 其状况 exports 字段,且该构建不需要多填充节点.js模块或像 Globals 这样的 process。 。 。 .

软件包从不读取环境变量或工作目录: 主机解决了工程的根路径, 并按 rootPath 选项.

快速启动

将 ESLint 配置中的边界部分正常化并获得其问题:

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]],
//   },
// ]

核心概念

诊断

函数因其输入中出现问题而永远不会打印或抛出. 他们把每个问题都当作 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:如何处理输入.
  • "error":输入被拒绝,因为ESLint拒绝失败规则计划选项.
  • "warning":输入被忽略或没有效果.
  • "deprecation":输入使用仍然有效的遗留语法.
• title 财务报告和审定财务报表 detail:ESLint插件所打印的文本. detail 是可选的,它通常以链接到文件结尾.
• paths页:1 路径 每个受影响的条目.

在多个条目中发现的一个问题被一次返回,其中所有条目的路径,诊断结果以ESLint插件打印的顺序来.

诊断路径

一个路径是导致受影响的条目的对象密钥和数组索引的列表,从返回它的函数输入的根起. 一条空道, [],表示整个输入.

主机可以使用路径在自己的界面中指向条目,比如在编辑器中突出显示.

正常化值

normalizeConfig 财务报告和审定财务报表 normalizeSettings 返回 a ConfigResult, (中文(简体) ), { value, diagnostics }编辑 value 总是设置的,不管输入: 缺失的设置得到它们的默认值,遗留的表单被转换,无效的条目被忽略,所以即使有诊断,一个主机也可以使用.

使用量

规范配置

normalizeConfig 取ESLint配置对象的边界部分, { settings, rules }。它使设置与 normalizeSettings,并验证插件的每个规则条目,作为ESLint验证,然后作为插件验证:

严重程度可以单写, "warn",或作为数组的第一个项, ["warn", { ... }]。规则以短名键入 value.rules选项 dependencies 规则,以及被掠夺者 element-types 规则,与 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"]],
//   },
// ]

当插件在 ESLint 配置中以另一个名称注册时, 将其传递为 pluginName。只读取前缀的规则:

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 } }

[注] 设置保留 boundaries/ 前缀,无论插件名称是什么,因为ESLint插件读取它们.

规范设置

normalizeSettings 拿着 settings 仅读取其 boundaries/* 键。 它应用每个缺失设置的默认值,转换遗留设置,例如 boundaries/types 或者说 boundaries/elements-single-type,将无效的条目删除。 这个 设置 : 列出每个属性及其默认值.

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"]],
//   },
// ]

这个 rootPath 选项是工程的根路径,由主机解决。 ESLint 插件从 boundaries/root-path 设置 ESLINT_PLUGIN_BOUNDARIES_ROOT_PATH 环境变量和工作目录。 没有选择,正常化 rootPath 这是 boundaries/root-path 设置为正文.

[注] 当 boundaries/legacy-warnings 设置是 false中,不报告遗留语法:在设置中,也不通过 normalizeConfig,在规则选项中.

验证规则选项

validateRuleOptions 验证单个规则条目的选项对象,紧后的项目。 正如ESLint所做的那样,它根据规则的策略来验证它,然后,对于有政策的规则,它检查其选择者的形状,当 legacyWarnings 实值 true,他们的被贬损的语法.

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]],
//   },
// ]

当选项失败规则计划时,计划错误是唯一的诊断,因为ESLint从未运行一个选项失败的规则. 已经运行了 ESLint 的宿主, 它验证了计划本身, 通过了 schema: false 跳过它:

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 });
// []

[注] 规则名称总是有 boundaries/ 前缀,无论插件在 ESLint 配置中注册的名称.

规范依赖规则选项

normalizeDependenciesRuleOptions 应用选项的默认值 dependencies 统治和规范其政策的选择者,所以一个主机可以和它们匹配 @boundaries/elements。它假设通过规则方案,并报告没有问题:首先通过 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,
// }

[尖叫声] 常态化的选取者与纪念 @boundaries/elements不要改变它们.

获取规则选项的外观

getRuleOptionsSchema 返回规则选项的 JSON 方案, 如 ESLint 插件在规则中声明 meta.schema: 包含每个选项的图案的数组, 当规则没有选项时为空 .

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");
// []

[尖叫声] 返回的策略在呼叫之间共享. 不要改变他们.

API 参考

职能

normalizeConfig

将ESLint配置的边界部分正常化, { settings, rules }。见 规范配置。 。 。 .

• 参数数字 :
  • config数字 : unknown ——配置对象. 内容 settings 财务报告和审定财务报表 rules 是可选的; 任何其它密钥都会被忽略.
  • options数字 : NormalizeConfigOptions - 可选的.
    • pluginName数字 : string - 可选的。 规则名称在 rules默认 "boundaries"。 。 。 .
    • rootPath数字 : string - 可选的。 项目的根道,已经由主机解决了. 没有它,正常化的 rootPath 这是 boundaries/root-path 设置为正文.
• 回返数字 : ConfigResult<ConfigNormalized> —— 规范化的配置和所发现的问题, 有来自配置对象根的路径.

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

normalizeSettings

规范化 boundaries/* 设置。 见 规范设置。 。 。 .

• 参数数字 :
  • settings数字 : Record<string, unknown> | undefined - 电话 settings 一个 ESLint 配置的对象。 仅限其 boundaries/* 键被读取.
  • options数字 : NormalizeSettingsOptions - 可选的.
    • rootPath数字 : string - 可选的。 项目的根道,已经由主机解决了. 没有它,正常化的 rootPath 这是 boundaries/root-path 设置为正文.
• 回返数字 : ConfigResult<SettingsNormalized> —— 常规设置和发现的问题, 以及设置对象根的路径 .

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

validateRuleOptions

验证规则条目的选项。 见 验证规则选项。 。 。 .

• 参数数字 :
  • ruleName数字 : RuleName - 规则的名称,加上 boundaries/ 前缀, 如 "boundaries/dependencies"。 。 。 .
  • options数字 : unknown - 规则条目的选项对象,或 undefined 当条目没有选项时.
  • validation数字 : RuleOptionsValidation - 什么来验证.
    • legacyWarnings数字 : boolean ——是否将政策贬值的语法报告为: boundaries/legacy-warnings 设置是.
    • schema数字 : boolean - 可选的。 是否按照 ESLint 对规则的规则验证选项 meta.schema默认 true; 已经运行 ESLint 通道的主机 false。 。 。 .
• 回返数字 : Diagnostic[] ——发现的问题,从选项对象的根出出路径. 当计划验证失败时, 只有错误 .

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

normalizeDependenciesRuleOptions

应用选项的默认值 dependencies 统治政策的选择者并使其正常化。 见 规范依赖规则选项。 。 。 .

• 参数数字 :
  • options数字 : DependenciesRuleOptions | undefined - 备选案文 dependencies 规则,或 element-types 规则,已经验证 与规则的策略.
• 回返数字 : DependenciesRuleOptionsNormalized ——适用其缺省选项. 这些政策来自 policies,或从被贬值的 rules 何时 policies 未设定,每个都保留其索引.

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

getRuleOptionsSchema

返回规则选项的 JSON 方案。 见 获取规则选项的外观。 。 。 .

• 参数数字 :
  • ruleName数字 : RuleName - 规则的名称,加上 boundaries/ 前缀.
• 回返数字 : JsonSchema[] ——规则的每个选项的图案,当规则没有选项时为空.

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

类型警卫

每人收到一张 value 类型 unknown 返回时 true 当值为类型时.

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

Docs 链接

链接的构建者 jsbounders.dev (英语) 诊断带。 每个 anchor 参数是可选的 string,以 #<anchor>,每个函数返回 a string。 。 。 .

path, (中文(简体) ), versionFrom 财务报告和审定财务报表 versionTo 为: strings,和 ruleName 是一个 RuleName。 。 。 .

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

常数

地图的值也逐一导出, 例如 DEPENDENCIES, (中文(简体) ), DEPENDENCY_NODE_IMPORT, (中文(简体) ), RULE_EFFECT_ALLOW 或者说 NO_UNKNOWN_DEPENDENCIES_REQUIRE_ANY。 。 。 .

类型参考

结果类型

ConfigResult

归来 normalizeConfig 财务报告和审定财务报表 normalizeSettings,作为 ConfigResult<T>。 。 。 .

Diagnostic

输入中发现的问题 。 见 诊断。 。 。 .

普通类型

ConfigNormalized

这个 value 返回时间 normalizeConfig。 。 。 .

RuleEntryNormalized

规则条目 ConfigNormalized,作为 RuleEntryNormalized<Name>。 。 。 .

SettingsNormalized

这个 value 返回时间 normalizeSettings,则 settings 联 合 国 ConfigNormalized。 。 。 .

ElementDescriptors, (中文(简体) ), FileDescriptors 财务报告和审定财务报表 FlagAsExternalOptions 属于类型 @boundaries/elements。 。 。 .

DebugSettingNormalized

DependenciesRuleOptionsNormalized

归来 normalizeDependenciesRuleOptions,则 options 会 议 日 程 和 议 程 dependencies 财务报告和审定财务报表 element-types 条目 ConfigNormalized。 。 。 .

DependenciesPolicyNormalized

选择者类型是类型 @boundaries/elements,在它选取的参考文献中描述它们.

设置和规则选项类型

软件包会导出用户写作的种类,所以一个主机可以输入自己的配置对象. 主要有:

这个 no-ignored-dependencies, (中文(简体) ), no-ignored 财务报告和审定财务报表 no-unknown-files 规则没有选择. DependenciesRule, (中文(简体) ), DependenciesRuleNormalized, (中文(简体) ), EntryPointRule, (中文(简体) ), ExternalRule, (中文(简体) ), ExternalLibrarySelectors, (中文(简体) ), RulePolicy 财务报告和审定财务报表 AliasSetting 已贬值.

捐款

欢迎贡献者. 请读一下 提供指南 财务报告和审定财务报表 行为守则。 。 。 .

许可证

麻省理工学院,看 自由主义 详细情况.