@boundaries/eslint-plugin 5.4.0 → 6.0.0-beta.1

package/dist/Settings/Helpers.d.ts

@@ -1,5 +1,57 @@
 import type { DependencyKind } from "@boundaries/elements";
-import type { DependencyNodeKey, SettingsKey, RulePolicy, RuleShortName, RuleName, RuleMainKey } from "./Settings.types";
+import type { DependencyNodeKey, SettingsKey, RulePolicy, RuleShortName, RuleName, RuleMainKey } from "../Shared/Settings.types";
+/**
+ * Returns the documentation URL for an ESLint rule.
+ * @param ruleName The name of the rule.
+ * @param anchor Optional anchor to a specific section in the documentation page.
+ * @returns The documentation URL for the ESLint rule.
+ */
+export declare function docsUrl(path: string, anchor?: string): string;
+/**
+ * Returns the documentation URL for an ESLint rule.
+ * @param ruleName The name of the rule.
+ * @param anchor Optional anchor to a specific section in the documentation page.
+ * @returns The documentation URL for the ESLint rule.
+ */
+export declare function ruleDocsUrl(ruleName: RuleName, anchor?: string): string;
+/**
+ * Returns a "more info" message with the documentation URL for a given path.
+ * @param path The path to the documentation page.
+ * @param anchor Optional anchor to a specific section in the documentation page.
+ * @returns A message containing the documentation URL.
+ */
+export declare function moreInfoLink(path: string, anchor?: string): string;
+/**
+ * Returns a migration guide link for a specific version upgrade.
+ * @param versionFrom - The version being upgraded from.
+ * @param versionTo - The version being upgraded to.
+ * @param anchor - Optional anchor to a specific section in the migration guide.
+ * @returns A message containing the migration guide URL for the specified version upgrade.
+ */
+export declare function migrationGuideLink(versionFrom: string, versionTo: string, anchor?: string): string;
+/**
+ * Returns a migration guide link for upgrading from version 5 to version 6.
+ * @param anchor - Optional anchor to a specific section in the migration guide.
+ * @returns A message containing the migration guide URL for upgrading from version 5 to version 6.
+ */
+export declare function migrationToV6GuideLink(anchor?: string): string;
+/**
+ * Returns a migration guide link for upgrading from version 1 to version 2.
+ * @param anchor - Optional anchor to a specific section in the migration guide.
+ * @returns A message containing the migration guide URL for upgrading from version 1 to version 2.
+ */
+export declare function migrationToV2GuideLink(anchor?: string): string;
+/**
+ * Returns a settings information link for the plugin settings documentation.
+ * @param anchor - Optional anchor to a specific section in the settings documentation.
+ * @returns A message containing the settings information URL for the plugin settings documentation.
+ */
+export declare function moreInfoSettingsLink(anchor?: string): string;
+/**
+ * Warns about the deprecation of a rule and encourages migration to the "dependencies" rule.
+ * @param ruleName The name of the deprecated rule.
+ */
+export declare function warnMigrationToDependencies(ruleName: RuleName): void;
 /**
  * Type guard to check if a value is a valid DependencyKind.
  * @param value The value to check.
@@ -37,5 +89,35 @@ export declare function isRuleName(value: unknown): value is RuleName;
  * @returns True if the value is a valid rule short name, false otherwise.
  */
 export declare function isRuleShortName(value: unknown): value is RuleShortName;
+/**
+ * Type guard for legacy element descriptors declared as plain strings.
+ *
+ * @param type - Value to check.
+ * @returns `true` when the value is a legacy string descriptor.
+ */
 export declare function isLegacyType(type: unknown): type is string;
+/**
+ * Type guard to check if a value is a legacy element selector (string or tuple format).
+ * @param value - The value to check.
+ * @returns True if the value is a legacy element selector, false otherwise.
+ */
+export declare function isLegacyElementSelector(value: unknown): value is string | [string, Record<string, unknown>];
+/**
+ * Detects if legacy element selector syntax is used.
+ * @param selector - The selector to check (can be a single selector or an array of selectors).
+ * @returns True if legacy syntax was detected, false otherwise.
+ */
+export declare function detectLegacyElementSelector(selector: unknown): boolean;
+/**
+ * Detects if legacy template syntax is used in selectors.
+ * @param selector - The selector to check (can be a single selector or an array of selectors).
+ * @returns True if legacy template syntax was detected, false otherwise.
+ */
+export declare function detectLegacyTemplateSyntax(selector: unknown): boolean;
+/**
+ * Returns the canonical main selector key used by schema and option checks.
+ *
+ * @param key - Optional rule main key (`from`, `to`, or `target`).
+ * @returns The same key with default fallback to `from`.
+ */
 export declare function rulesMainKey(key?: RuleMainKey): RuleMainKey;

package/dist/Settings/Helpers.js

@@ -1,5 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.docsUrl = docsUrl;
+exports.ruleDocsUrl = ruleDocsUrl;
+exports.moreInfoLink = moreInfoLink;
+exports.migrationGuideLink = migrationGuideLink;
+exports.migrationToV6GuideLink = migrationToV6GuideLink;
+exports.migrationToV2GuideLink = migrationToV2GuideLink;
+exports.moreInfoSettingsLink = moreInfoSettingsLink;
+exports.warnMigrationToDependencies = warnMigrationToDependencies;
 exports.isImportKind = isImportKind;
 exports.isDependencyNodeKey = isDependencyNodeKey;
 exports.isSettingsKey = isSettingsKey;
@@ -7,10 +15,112 @@ exports.isRulePolicy = isRulePolicy;
 exports.isRuleName = isRuleName;
 exports.isRuleShortName = isRuleShortName;
 exports.isLegacyType = isLegacyType;
+exports.isLegacyElementSelector = isLegacyElementSelector;
+exports.detectLegacyElementSelector = detectLegacyElementSelector;
+exports.detectLegacyTemplateSyntax = detectLegacyTemplateSyntax;
 exports.rulesMainKey = rulesMainKey;
 const elements_1 = require("@boundaries/elements");
-const Support_1 = require("../Support");
-const Settings_types_1 = require("./Settings.types");
+const Debug_1 = require("../Debug");
+const Shared_1 = require("../Shared");
+const Settings_types_1 = require("../Shared/Settings.types");
+/**
+ * Removes the plugin namespace from a rule name.
+ * @param ruleName The name of the rule.
+ * @returns The rule name without the plugin namespace.
+ */
+function removePluginNamespace(ruleName) {
+    return ruleName.replace(`${Settings_types_1.PLUGIN_NAME}/`, "");
+}
+/**
+ * Adapts the rule name to be used in a URL.
+ * @param ruleName The name of the rule.
+ * @returns The adapted rule name for URL usage.
+ */
+function adaptRuleNameToUrl(ruleName) {
+    if (ruleName === Settings_types_1.RULE_NAMES_MAP.ELEMENT_TYPES) {
+        return Settings_types_1.RULE_NAMES_MAP.DEPENDENCIES;
+    }
+    return ruleName;
+}
+/**
+ * Returns the documentation URL for an ESLint rule.
+ * @param ruleName The name of the rule.
+ * @param anchor Optional anchor to a specific section in the documentation page.
+ * @returns The documentation URL for the ESLint rule.
+ */
+function docsUrl(path, anchor) {
+    const anchorSuffix = anchor ? `#${anchor}` : "";
+    return `${Settings_types_1.WEBSITE_URL}/docs/${path}/${anchorSuffix}`;
+}
+/**
+ * Returns the documentation path for a given rule name.
+ * @param ruleName The name of the rule.
+ * @returns The documentation path for the given rule name.
+ */
+function getRuleDocsPath(ruleName) {
+    return `rules/${removePluginNamespace(adaptRuleNameToUrl(ruleName))}`;
+}
+/**
+ * Returns the documentation URL for an ESLint rule.
+ * @param ruleName The name of the rule.
+ * @param anchor Optional anchor to a specific section in the documentation page.
+ * @returns The documentation URL for the ESLint rule.
+ */
+function ruleDocsUrl(ruleName, anchor) {
+    return docsUrl(getRuleDocsPath(ruleName), anchor);
+}
+/**
+ * Returns a "more info" message with the documentation URL for a given path.
+ * @param path The path to the documentation page.
+ * @param anchor Optional anchor to a specific section in the documentation page.
+ * @returns A message containing the documentation URL.
+ */
+function moreInfoLink(path, anchor) {
+    return `More info: ${docsUrl(path, anchor)}`;
+}
+/**
+ * Returns a migration guide link for a specific version upgrade.
+ * @param versionFrom - The version being upgraded from.
+ * @param versionTo - The version being upgraded to.
+ * @param anchor - Optional anchor to a specific section in the migration guide.
+ * @returns A message containing the migration guide URL for the specified version upgrade.
+ */
+function migrationGuideLink(versionFrom, versionTo, anchor) {
+    return moreInfoLink(`releases/migration-guides/v${versionFrom}-to-v${versionTo}`, anchor);
+}
+/**
+ * Returns a migration guide link for upgrading from version 5 to version 6.
+ * @param anchor - Optional anchor to a specific section in the migration guide.
+ * @returns A message containing the migration guide URL for upgrading from version 5 to version 6.
+ */
+function migrationToV6GuideLink(anchor) {
+    return migrationGuideLink("5", "6", anchor);
+}
+/**
+ * Returns a migration guide link for upgrading from version 1 to version 2.
+ * @param anchor - Optional anchor to a specific section in the migration guide.
+ * @returns A message containing the migration guide URL for upgrading from version 1 to version 2.
+ */
+function migrationToV2GuideLink(anchor) {
+    return migrationGuideLink("1", "2", anchor);
+}
+/**
+ * Returns a settings information link for the plugin settings documentation.
+ * @param anchor - Optional anchor to a specific section in the settings documentation.
+ * @returns A message containing the settings information URL for the plugin settings documentation.
+ */
+function moreInfoSettingsLink(anchor) {
+    return moreInfoLink(`setup/settings`, anchor);
+}
+/**
+ * Warns about the deprecation of a rule and encourages migration to the "dependencies" rule.
+ * @param ruleName The name of the deprecated rule.
+ */
+function warnMigrationToDependencies(ruleName) {
+    (0, Debug_1.warnOnce)(`Rule "${ruleName}" is deprecated and will be removed in future versions.`, `Please migrate to the "${Settings_types_1.RULE_NAMES_MAP.DEPENDENCIES}" rule with appropriate selectors. ${moreInfoLink(getRuleDocsPath(ruleName), 
+    // cspell: disable-next-line
+    "migration-to-boundariesdependencies")}`);
+}
 /**
  * Type guard to check if a value is a valid DependencyKind.
  * @param value The value to check.
@@ -18,7 +128,7 @@ const Settings_types_1 = require("./Settings.types");
  * @deprecated Use isDependencyKind instead.
  */
 function isImportKind(value) {
-    return ((0, Support_1.isString)(value) &&
+    return ((0, Shared_1.isString)(value) &&
         Object.values(elements_1.DEPENDENCY_KINDS_MAP).includes(value));
 }
 /**
@@ -27,7 +137,7 @@ function isImportKind(value) {
  * @returns True if the value is a valid DependencyNodeKey, false otherwise.
  */
 function isDependencyNodeKey(value) {
-    return ((0, Support_1.isString)(value) &&
+    return ((0, Shared_1.isString)(value) &&
         Object.values(Settings_types_1.DEPENDENCY_NODE_KEYS_MAP).includes(value));
 }
 /**
@@ -36,7 +146,7 @@ function isDependencyNodeKey(value) {
  * @returns True if the value is a valid settings key, false otherwise.
  */
 function isSettingsKey(value) {
-    return ((0, Support_1.isString)(value) &&
+    return ((0, Shared_1.isString)(value) &&
         Object.values(Settings_types_1.SETTINGS_KEYS_MAP).includes(value));
 }
 /**
@@ -45,7 +155,7 @@ function isSettingsKey(value) {
  * @returns True if the value is a valid RulePolicy, false otherwise.
  */
 function isRulePolicy(value) {
-    return ((0, Support_1.isString)(value) &&
+    return ((0, Shared_1.isString)(value) &&
         (value === Settings_types_1.RULE_POLICY_ALLOW || value === Settings_types_1.RULE_POLICY_DISALLOW));
 }
 /**
@@ -64,9 +174,89 @@ function isRuleName(value) {
 function isRuleShortName(value) {
     return Settings_types_1.RULE_SHORT_NAMES.includes(value);
 }
+/**
+ * Type guard for legacy element descriptors declared as plain strings.
+ *
+ * @param type - Value to check.
+ * @returns `true` when the value is a legacy string descriptor.
+ */
 function isLegacyType(type) {
-    return (0, Support_1.isString)(type);
+    return (0, Shared_1.isString)(type);
 }
+/**
+ * Type guard to check if a value is a legacy element selector (string or tuple format).
+ * @param value - The value to check.
+ * @returns True if the value is a legacy element selector, false otherwise.
+ */
+function isLegacyElementSelector(value) {
+    // String format: "type"
+    if ((0, Shared_1.isString)(value)) {
+        return true;
+    }
+    // Tuple format: ["type", { captured values }]
+    if (Array.isArray(value) && value.length === 2 && (0, Shared_1.isString)(value[0])) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Detects if legacy element selector syntax is used.
+ * @param selector - The selector to check (can be a single selector or an array of selectors).
+ * @returns True if legacy syntax was detected, false otherwise.
+ */
+function detectLegacyElementSelector(selector) {
+    if (Array.isArray(selector)) {
+        for (const sel of selector) {
+            if (isLegacyElementSelector(sel)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    else if (selector) {
+        return isLegacyElementSelector(selector);
+    }
+    return false;
+}
+/**
+ * Checks if a string contains legacy template syntax ${...}.
+ * @param value - The value to check.
+ * @returns True if the value contains legacy template syntax, false otherwise.
+ */
+function hasLegacyTemplateSyntax(value) {
+    return value.includes("${");
+}
+/**
+ * Recursively checks if a selector contains legacy template syntax.
+ * @param value - The value to check (can be string, object, array, etc.).
+ * @returns True if legacy template syntax was detected, false otherwise.
+ */
+function checkForLegacyTemplateSyntax(value) {
+    if ((0, Shared_1.isString)(value)) {
+        return hasLegacyTemplateSyntax(value);
+    }
+    if ((0, Shared_1.isArray)(value)) {
+        return value.some(checkForLegacyTemplateSyntax);
+    }
+    if ((0, Shared_1.isNull)(value) || !(0, Shared_1.isObject)(value)) {
+        return false;
+    }
+    return Object.values(value).some(checkForLegacyTemplateSyntax);
+}
+/**
+ * Detects if legacy template syntax is used in selectors.
+ * @param selector - The selector to check (can be a single selector or an array of selectors).
+ * @returns True if legacy template syntax was detected, false otherwise.
+ */
+function detectLegacyTemplateSyntax(selector) {
+    return checkForLegacyTemplateSyntax(selector);
+}
+/**
+ * Returns the canonical main selector key used by schema and option checks.
+ *
+ * @param key - Optional rule main key (`from`, `to`, or `target`).
+ * @returns The same key with default fallback to `from`.
+ */
 function rulesMainKey(key = Settings_types_1.FROM) {
     return key;
 }

package/dist/Settings/Settings.d.ts

@@ -1,6 +1,23 @@
 import type { ElementDescriptors } from "@boundaries/elements";
-import type { Settings } from "./Settings.types";
+import type { Settings } from "../Shared/Settings.types";
+/**
+ * Converts legacy string element descriptors into object descriptors.
+ *
+ * @param typesFromSettings - Raw `boundaries/elements` setting value.
+ * @returns Normalized element descriptors compatible with current matcher API.
+ */
 export declare function transformLegacyTypes(typesFromSettings?: string[] | ElementDescriptors): ElementDescriptors;
+/**
+ * Extracts element type names from normalized element descriptors.
+ *
+ * @param descriptors - Normalized descriptors from settings.
+ * @returns List of defined element type names.
+ */
 export declare function getElementsTypeNames(descriptors: ElementDescriptors): string[];
+/**
+ * Resolves the effective root path used by boundaries matchers.
+ *
+ * @param settings - Validated plugin settings.
+ * @returns Absolute root path used for dependency and element resolution.
+ */
 export declare function getRootPath(settings: Settings): string;
-export declare function isDebugModeEnabled(): string | undefined;

package/dist/Settings/Settings.js

@@ -3,18 +3,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.transformLegacyTypes = transformLegacyTypes;
 exports.getElementsTypeNames = getElementsTypeNames;
 exports.getRootPath = getRootPath;
-exports.isDebugModeEnabled = isDebugModeEnabled;
 const node_path_1 = require("node:path");
-const Support_1 = require("../Support");
+const Settings_types_1 = require("../Shared/Settings.types");
 const Helpers_1 = require("./Helpers");
-const Settings_types_1 = require("./Settings.types");
-const { VALID_MODES, ROOT_PATH, ENV_ROOT_PATH, DEBUG } = Settings_types_1.SETTINGS;
+const { VALID_MODES, ROOT_PATH, ENV_ROOT_PATH } = Settings_types_1.SETTINGS;
 // TODO, remove in next major version
+/**
+ * Converts legacy string element descriptors into object descriptors.
+ *
+ * @param typesFromSettings - Raw `boundaries/elements` setting value.
+ * @returns Normalized element descriptors compatible with current matcher API.
+ */
 function transformLegacyTypes(typesFromSettings) {
     const types = typesFromSettings || [];
-    if (!(0, Support_1.isArray)(types)) {
-        return [];
-    }
     return types.map((type) => {
         // backward compatibility with v1
         if ((0, Helpers_1.isLegacyType)(type)) {
@@ -32,9 +33,21 @@ function transformLegacyTypes(typesFromSettings) {
         };
     });
 }
+/**
+ * Extracts element type names from normalized element descriptors.
+ *
+ * @param descriptors - Normalized descriptors from settings.
+ * @returns List of defined element type names.
+ */
 function getElementsTypeNames(descriptors) {
     return descriptors.map((element) => element.type).filter(Boolean);
 }
+/**
+ * Resolves the effective root path used by boundaries matchers.
+ *
+ * @param settings - Validated plugin settings.
+ * @returns Absolute root path used for dependency and element resolution.
+ */
 function getRootPath(settings) {
     const rootPathUserSetting = process.env[ENV_ROOT_PATH] || settings[ROOT_PATH];
     if (rootPathUserSetting) {
@@ -44,6 +57,3 @@ function getRootPath(settings) {
     }
     return process.cwd();
 }
-function isDebugModeEnabled() {
-    return process.env[DEBUG];
-}