@boundaries/elements 1.1.2 → 1.2.0

package/README.md

@@ -25,6 +25,7 @@
   - [Using Matchers](#using-matchers)
     - [Element Matching](#element-matching)
     - [Dependency Matching](#dependency-matching)
+  - [Flagging Dependencies as External](#flagging-dependencies-as-external)
 - [API Reference](#api-reference)
 - [Legacy Selectors](#legacy-selectors)
 - [Contributing](#contributing)
@@ -120,6 +121,13 @@ When creating an `Elements` instance, you can provide configuration options that
 const elements = new Elements({
   ignorePaths: ["**/dist/**", "**/build/**", "**/node_modules/**"],
   includePaths: ["src/**/*"],
+  rootPath: "/absolute/path/to/project",
+  flagAsExternal: {
+    unresolvableAlias: true,
+    inNodeModules: true,
+    outsideRootPath: true,
+    customSourcePatterns: ["@myorg/*"],
+  },
 });
 ```
 
@@ -129,6 +137,15 @@ const elements = new Elements({
 - **`includePaths`**: Micromatch pattern(s) to include only specific paths (default: all paths)
 - **`legacyTemplates`**: Whether to enable legacy template syntax support (default: `true`, but it will be `false` in future releases). This allows using `${variable}` syntax in templates for backward compatibility.
 - **`cache`**: Whether to enable internal caching to improve performance (default: `true`)
+- **`rootPath`**: Absolute path to the project root. When configured, file paths should be provided as absolute paths to allow the package to determine which files are outside the project root (default: `undefined`)
+- **`flagAsExternal`**: Configuration for categorizing dependencies as external or local. Multiple conditions can be specified, and dependencies will be categorized as external if ANY condition is met (OR logic). See [Flagging Dependencies as External](#flagging-dependencies-as-external) for details.
+
+> [!NOTE]
+> **Pattern Matching with `rootPath`:**
+> When `rootPath` **is configured**:
+> - **Matching patterns** in element descriptors are **relative to the `rootPath`**. The package automatically converts absolute paths to relative paths internally for pattern matching.
+> - In **`file` and `folder` modes**, patterns are evaluated **right-to-left** (from the end of the path), so the relativity to `rootPath` is typically less important. For example, a pattern like `*.model.ts` will match any file ending with `.model.ts` regardless of its location within `rootPath`.
+> - In **`full` mode**, patterns must match the complete relative path from `rootPath`. Files outside `rootPath` maintain their absolute paths and require absolute patterns to match.
 
 ### Creating a Matcher
 
@@ -345,6 +362,114 @@ const isDependencyMatch = matcher.isMatch(
 > [!TIP]
 > You can also provide an array of selectors both to the `from` and `to` properties of the dependency selector. In this case, the method will return `true` if the dependency matches any combination of the provided selectors (OR logic).
 
+### Flagging Dependencies as External
+
+The `flagAsExternal` configuration allows you to control how dependencies are categorized as external or local. This is especially useful in monorepo setups where you may want to treat inter-package dependencies as external even though they're within the same repository.
+
+**Multiple conditions can be specified, and dependencies will be flagged as external if ANY condition is met (OR logic).**
+
+#### Available Options
+
+- **`unresolvableAlias`** (boolean, default: `true`): Non-relative imports whose path cannot be resolved are categorized as external
+  
+  ```typescript
+  const elements = new Elements({
+    flagAsExternal: { unresolvableAlias: true },
+  });
+  const matcher = elements.getMatcher([/* descriptors */]);
+  
+  // describeDependency({ from, to, source, kind }):
+  // to: null, source: 'unresolved-module' -> origin: 'external'
+  // to: '/project/src/Button.ts', source: './Button' -> origin: 'local'
+  ```
+
+- **`inNodeModules`** (boolean, default: `true`): Non-relative paths that include `node_modules` in the resolved path are categorized as external
+  
+  ```typescript
+  const elements = new Elements({
+    flagAsExternal: { inNodeModules: true },
+  });
+  const matcher = elements.getMatcher([/* descriptors */]);
+  
+  // describeDependency({ from, to, source, kind }):
+  // to: '/project/node_modules/react/index.js', source: 'react' -> origin: 'external'
+  // to: '/project/src/utils.ts', source: './utils' -> origin: 'local'
+  ```
+
+- **`outsideRootPath`** (boolean, default: `false`): Dependencies whose resolved path is outside the configured `rootPath` are categorized as external. This is particularly useful in monorepo setups.
+  
+  > **⚠️ Important:** This option requires `rootPath` to be configured. When using this option, all file paths must be absolute and include the `rootPath` prefix for files within the project.
+  
+  ```typescript
+  const elements = new Elements({
+    rootPath: '/monorepo/packages/app',
+    flagAsExternal: { outsideRootPath: true },
+  });
+  const matcher = elements.getMatcher([/* descriptors */]);
+  
+  // describeDependency({ from, to, source, kind }):
+  // to: '/monorepo/packages/shared/index.ts', source: '@myorg/shared' -> origin: 'external'
+  // to: '/monorepo/packages/app/src/utils/helper.ts', source: './utils/helper' -> origin: 'local'
+  ```
+
+- **`customSourcePatterns`** (string[], default: `[]`): Array of micromatch patterns that, when matching the import/export source string, categorize the dependency as external
+  
+  ```typescript
+  const elements = new Elements({
+    flagAsExternal: { customSourcePatterns: ['@myorg/*', '~/**'] },
+  });
+  const matcher = elements.getMatcher([/* descriptors */]);
+  
+  // describeDependency({ from, to, source, kind }):
+  // source: '@myorg/shared' -> origin: 'external' (matches '@myorg/*')
+  // source: '~/utils/helper' -> origin: 'external' (matches '~/**')
+  // source: '@other/package' -> origin: 'local' (no match, unless inNodeModules is true or other conditions met)
+  ```
+
+#### Path Requirements with `rootPath`
+
+When `rootPath` is configured, the package needs absolute paths to correctly determine which files are outside the project root, but matching patterns must remain relative to `rootPath`, especially in `full` mode (because `file` and `folder` modes match progressively from the right, so they may be less affected by relativity).
+
+```typescript
+const elements = new Elements({
+  rootPath: '/project/packages/app',
+  flagAsExternal: {
+    outsideRootPath: true,
+  },
+});
+
+// Matching patterns are relative to rootPath
+const matcher = elements.getMatcher([
+  { type: 'component', pattern: 'src/**/*.ts', mode: 'full' }, // Relative to /project/packages/app
+]);
+
+// ✅ Correct: Using absolute file paths with relative patterns
+const dep = matcher.describeDependency({
+  from: '/project/packages/app/src/index.ts',      // absolute file path
+  to: '/project/packages/shared/index.ts',         // absolute file path
+  source: '@myorg/shared',
+  kind: 'value',
+});
+// Result: dep.to.origin === 'external' (outside rootPath)
+// Note: Pattern 'src/**/*.ts' matches because the package converts
+// absolute paths to relative internally for pattern matching
+
+// ❌ Incorrect: Using relative file paths (won't detect outsideRootPath correctly)
+const dep2 = matcher.describeDependency({
+  from: 'src/index.ts',                            // relative file path
+  to: '../shared/index.ts',                        // relative file path
+  source: '@myorg/shared',
+  kind: 'value',
+});
+// Result: Won't correctly detect if outside rootPath
+```
+
+> **💡 Key Points:**
+> - **File paths** in API calls (`from`, `to`, `filePath`) must be **absolute** when using `rootPath`
+> - **Matching patterns** in element descriptors stay **relative** to `rootPath`
+> - The package handles the conversion internally
+> - When not using `rootPath`, the package continues to work with relative paths as before, maintaining backward compatibility.
+
 ## API Reference
 
 ### Class: Elements

package/dist/index.browser.d.mts

@@ -2,6 +2,19 @@
  * Type representing a micromatch pattern, which can be a string or an array of strings.
  */
 type MicromatchPattern = string | string[];
+/**
+ * Configuration options for categorizing dependencies as external or local.
+ */
+type FlagAsExternalOptions = {
+    /** When true, non-relative dependencies whose path cannot be resolved are categorized as external (default: true) */
+    unresolvableAlias?: boolean;
+    /** When true, non-relative paths that include node_modules are categorized as external (default: true) */
+    inNodeModules?: boolean;
+    /** When true, dependencies whose resolved path is outside the configured root path are categorized as external (default: false) */
+    outsideRootPath?: boolean;
+    /** List of patterns (using micromatch syntax) that, when matching the source of the dependency, categorize it as external (default: []) */
+    customSourcePatterns?: string[];
+};
 /** Configuration options for the Config class */
 type ConfigOptions = {
     /** An array of path patterns to include when resolving elements. Defaults to all files if not specified */
@@ -15,15 +28,33 @@ type ConfigOptions = {
     legacyTemplates?: boolean;
     /** Whether to enable caching */
     cache?: boolean;
+    /** Configuration for categorizing dependencies as external or local */
+    flagAsExternal?: FlagAsExternalOptions;
+    /** Root path of the project, used for determining if dependencies are outside the project */
+    rootPath?: string;
+};
+type FlagAsExternalOptionsNormalized = {
+    /** When true, non-relative dependencies whose path cannot be resolved are categorized as external */
+    unresolvableAlias: boolean;
+    /** When true, non-relative paths that include node_modules are categorized as external */
+    inNodeModules: boolean;
+    /** When true, dependencies whose resolved path is outside the configured root path are categorized as external */
+    outsideRootPath: boolean;
+    /** List of patterns (using micromatch syntax) that, when matching the source of the dependency, categorize it as external */
+    customSourcePatterns: string[];
 };
-type ConfigOptionsNormalized = Omit<ConfigOptions, "legacyTemplates" | "cache"> & {
+type ConfigOptionsNormalized = Omit<ConfigOptions, "legacyTemplates" | "cache" | "flagAsExternal"> & {
     /** Whether to enable legacy template support */
     legacyTemplates: boolean;
     /** Cache configuration options */
     cache: boolean;
+    /** Configuration for categorizing dependencies as external or local */
+    flagAsExternal: FlagAsExternalOptionsNormalized;
+    /** Root path of the project, already normalized, and finishing with a slash, used for determining if dependencies are outside the project */
+    rootPath: string | undefined;
 };
 /** Options for descriptors */
-type DescriptorOptionsNormalized = Pick<ConfigOptionsNormalized, "includePaths" | "ignorePaths" | "cache">;
+type DescriptorOptionsNormalized = Pick<ConfigOptionsNormalized, "includePaths" | "ignorePaths" | "cache" | "flagAsExternal" | "rootPath">;
 /** Options for element matchers */
 type MatchersOptionsNormalized = Pick<ConfigOptionsNormalized, "legacyTemplates">;
 
@@ -1544,14 +1575,37 @@ declare class ElementsDescriptor {
      * @returns The base source of the external module. (e.g., for "@scope/package/submodule", it returns "@scope/package")
      */
     private _getExternalOrCoreModuleBaseSource;
+    /**
+     * Determines if a file path is outside the configured root path.
+     * @param filePath The file path to check.
+     * @returns True if the file path is outside the root path, false otherwise.
+     */
+    private _isOutsideRootPath;
+    /**
+     * Converts an absolute file path to a relative path if rootPath is configured.
+     * If rootPath is not configured, returns the path as-is (maintains backward compatibility).
+     * @param filePath The file path to convert (can be absolute or relative)
+     * @returns The relative path if rootPath is configured and path is absolute, otherwise the original path
+     */
+    private _toRelativePath;
+    /**
+     * Checks if a source string matches any of the provided patterns using micromatch.
+     * @param patterns - Array of micromatch patterns
+     * @param source - The source string to match against patterns
+     * @returns True if the source matches any pattern, false otherwise
+     */
+    private _matchesAnyPattern;
     /**
      * Determines if an element is external based on its file path and dependency source.
-     * Files inside "node_modules" are considered external.
-     * If the dependency source is not provided, only the file path is considered.
-     * If the dependency source is provided, it must not be a local path (i.e, it should start by "./", "../", or "/").
-     * @param filePath
-     * @param dependencySource
-     * @returns
+     * Uses the flagAsExternal configuration to evaluate multiple conditions with OR logic:
+     * - unresolvableAlias: Files whose path cannot be resolved (filePath is null)
+     * - inNodeModules: Non-relative paths that include "node_modules"
+     * - outsideRootPath: Resolved path is outside the configured root path (only if rootPath is configured)
+     * - customSourcePatterns: Source matches any of the configured patterns
+     * @param filePath The resolved file path (null if unresolved). Can be absolute if rootPath is configured, or relative if rootPath is not configured.
+     * @param isOutsideRootPath Whether the file path is outside the configured root path.
+     * @param dependencySource The import/export source string
+     * @returns True if any of the configured conditions is met, false otherwise
      */
     private _isExternalDependency;
     /**
@@ -1599,27 +1653,28 @@ declare class ElementsDescriptor {
     /**
      * Returns an external or core dependency element given its dependency source and file path.
      * @param dependencySource The source of the dependency.
-     * @param filePath The resolved file path of the dependency, if known.
+     * @param isOutsideRootPath Whether the file path is outside the configured root path.
+     * @param filePath The resolved file path of the dependency, if known. Can be absolute if rootPath is configured.
      * @returns The external or core dependency element, or null if it is a local dependency.
      */
     private _getExternalOrCoreDependencyElement;
     /**
      * Describes an element given its file path and dependency source, if any.
-     * @param filePath The path of the file to describe.
+     * @param filePath The path of the file to describe. Can be absolute if rootPath is configured, or relative if not.
      * @param dependencySource The source of the dependency, if the element to describe is so. It refers to the import/export path used to reference the file or external module.
      * @returns The description of the element. A dependency element if dependency source is provided, otherwise a file element.
      */
     private _describeElement;
     /**
      * Describes an element given its file path.
-     * @param filePath The path of the file to describe.
+     * @param filePath The path of the file to describe. Can be absolute if rootPath is configured, or relative if not.
      * @returns The description of the element.
      */
     describeElement(filePath?: string): FileElement;
     /**
      * Describes a dependency element given its dependency source and file path.
      * @param dependencySource The source of the dependency.
-     * @param filePath The path of the file being the dependency, if known.
+     * @param filePath The path of the file being the dependency, if known. Can be absolute if rootPath is configured, or relative if not.
      * @returns The description of the dependency element.
      */
     describeDependencyElement(dependencySource: string, filePath?: string): DependencyElementDescription;
@@ -1791,4 +1846,4 @@ declare class CacheManager<CacheKey extends NotUndefined, CachedValue> {
     setFromSerialized(serializedCache: Record<string, CachedValue>): void;
 }
 
-export { type BaseDependencyElement, type BaseElement, type BaseElementDescriptor, type BaseElementSelector, type BaseElementSelectorData, type BaseElementSelectorWithOptions, type BaseElementsSelector, CacheManager, type CapturedValues, type CapturedValuesSelector, type ConfigOptions, type ConfigOptionsNormalized, type CoreDependencyElement, DEPENDENCY_KINDS_MAP, DEPENDENCY_KIND_TYPE, DEPENDENCY_KIND_TYPEOF, DEPENDENCY_KIND_VALUE, DEPENDENCY_RELATIONSHIPS_INVERTED_MAP, DEPENDENCY_RELATIONSHIPS_MAP, DependenciesDescriptor, type DependenciesDescriptorSerializedCache, DependenciesMatcher, type DependenciesMatcherSerializedCache, type DependencyDescription, type DependencyElementDescription, type DependencyElementSelector, type DependencyElementSelectorData, type DependencyElementSelectorWithOptions, type DependencyElementsSelector, type DependencyKind, type DependencyMatchResult, type DependencyRelationship, type DependencySelector, type DependencySelectorNormalized, type DescribeDependencyOptions, type DescriptionsSerializedCache, type DescriptorOptionsNormalized, Descriptors, type DescriptorsSerializedCache, ELEMENT_DESCRIPTOR_MODES_MAP, ELEMENT_ORIGINS_MAP, type ElementDescription, type ElementDescriptor, type ElementDescriptorMode, type ElementDescriptorPattern, type ElementDescriptorWithCategory, type ElementDescriptorWithType, type ElementDescriptorWithTypeAndCategory, type ElementDescriptors, type ElementOrigin, type ElementParent, type ElementSelector, type ElementSelectorData, type ElementSelectorWithOptions, type ElementSelectors, Elements, type ElementsDependencyInfo, ElementsDescriptor, type ElementsDescriptorSerializedCache, ElementsMatcher, type ElementsMatcherSerializedCache, type ElementsSelector, type ElementsSerializedCache, type ExternalDependencyElement, type ExternalLibrariesSelector, type ExternalLibrarySelector, type ExternalLibrarySelectorOptions, type ExternalLibrarySelectorWithOptions, type ExternalLibrarySelectors, type FileElement, type FileElementsSerializedCache, type IgnoredDependencyElement, type IgnoredElement, type LocalDependencyElement, type LocalDependencyElementKnown, type LocalDependencyElementUnknown, type LocalElementKnown, type LocalElementUnknown, Matcher, type MatcherOptions, type MatcherOptionsDependencySelectorsGlobals, type MatcherSerializedCache, type MatchersOptionsNormalized, type MicromatchPattern, type MicromatchSerializedCache, type NotUndefined, type ObjectCacheKey, type SelectableElement, type SimpleElementSelectorByType, type TemplateData, isBaseElement, isBaseElementDescriptor, isBaseElementSelectorData, isCapturedValuesSelector, isCoreDependencyElement, isDependencyDescription, isDependencyElementDescription, isDependencyKind, isDependencyRelationship, isDependencyRelationshipDescription, isDependencySelector, isElementDescription, isElementDescriptor, isElementDescriptorMode, isElementDescriptorPattern, isElementDescriptorWithCategory, isElementDescriptorWithType, isElementSelector, isElementSelectorData, isElementSelectorWithLegacyOptions, isElementsDependencyInfo, isElementsSelector, isExternalDependencyElement, isExternalLibrariesSelector, isExternalLibrarySelector, isExternalLibrarySelectorOptions, isExternalLibrarySelectorOptionsWithPath, isExternalLibrarySelectorOptionsWithSpecifiers, isExternalLibrarySelectorWithOptions, isIgnoredElement, isInternalDependency, isKnownLocalElement, isLocalDependencyElement, isLocalElement, isSimpleElementSelectorByType, isUnknownLocalElement, normalizeElementsSelector };
+export { type BaseDependencyElement, type BaseElement, type BaseElementDescriptor, type BaseElementSelector, type BaseElementSelectorData, type BaseElementSelectorWithOptions, type BaseElementsSelector, CacheManager, type CapturedValues, type CapturedValuesSelector, type ConfigOptions, type ConfigOptionsNormalized, type CoreDependencyElement, DEPENDENCY_KINDS_MAP, DEPENDENCY_KIND_TYPE, DEPENDENCY_KIND_TYPEOF, DEPENDENCY_KIND_VALUE, DEPENDENCY_RELATIONSHIPS_INVERTED_MAP, DEPENDENCY_RELATIONSHIPS_MAP, DependenciesDescriptor, type DependenciesDescriptorSerializedCache, DependenciesMatcher, type DependenciesMatcherSerializedCache, type DependencyDescription, type DependencyElementDescription, type DependencyElementSelector, type DependencyElementSelectorData, type DependencyElementSelectorWithOptions, type DependencyElementsSelector, type DependencyKind, type DependencyMatchResult, type DependencyRelationship, type DependencySelector, type DependencySelectorNormalized, type DescribeDependencyOptions, type DescriptionsSerializedCache, type DescriptorOptionsNormalized, Descriptors, type DescriptorsSerializedCache, ELEMENT_DESCRIPTOR_MODES_MAP, ELEMENT_ORIGINS_MAP, type ElementDescription, type ElementDescriptor, type ElementDescriptorMode, type ElementDescriptorPattern, type ElementDescriptorWithCategory, type ElementDescriptorWithType, type ElementDescriptorWithTypeAndCategory, type ElementDescriptors, type ElementOrigin, type ElementParent, type ElementSelector, type ElementSelectorData, type ElementSelectorWithOptions, type ElementSelectors, Elements, type ElementsDependencyInfo, ElementsDescriptor, type ElementsDescriptorSerializedCache, ElementsMatcher, type ElementsMatcherSerializedCache, type ElementsSelector, type ElementsSerializedCache, type ExternalDependencyElement, type ExternalLibrariesSelector, type ExternalLibrarySelector, type ExternalLibrarySelectorOptions, type ExternalLibrarySelectorWithOptions, type ExternalLibrarySelectors, type FileElement, type FileElementsSerializedCache, type FlagAsExternalOptions, type FlagAsExternalOptionsNormalized, type IgnoredDependencyElement, type IgnoredElement, type LocalDependencyElement, type LocalDependencyElementKnown, type LocalDependencyElementUnknown, type LocalElementKnown, type LocalElementUnknown, Matcher, type MatcherOptions, type MatcherOptionsDependencySelectorsGlobals, type MatcherSerializedCache, type MatchersOptionsNormalized, type MicromatchPattern, type MicromatchSerializedCache, type NotUndefined, type ObjectCacheKey, type SelectableElement, type SimpleElementSelectorByType, type TemplateData, isBaseElement, isBaseElementDescriptor, isBaseElementSelectorData, isCapturedValuesSelector, isCoreDependencyElement, isDependencyDescription, isDependencyElementDescription, isDependencyKind, isDependencyRelationship, isDependencyRelationshipDescription, isDependencySelector, isElementDescription, isElementDescriptor, isElementDescriptorMode, isElementDescriptorPattern, isElementDescriptorWithCategory, isElementDescriptorWithType, isElementSelector, isElementSelectorData, isElementSelectorWithLegacyOptions, isElementsDependencyInfo, isElementsSelector, isExternalDependencyElement, isExternalLibrariesSelector, isExternalLibrarySelector, isExternalLibrarySelectorOptions, isExternalLibrarySelectorOptionsWithPath, isExternalLibrarySelectorOptionsWithSpecifiers, isExternalLibrarySelectorWithOptions, isIgnoredElement, isInternalDependency, isKnownLocalElement, isLocalDependencyElement, isLocalElement, isSimpleElementSelectorByType, isUnknownLocalElement, normalizeElementsSelector };

package/dist/index.browser.d.ts

@@ -2,6 +2,19 @@
  * Type representing a micromatch pattern, which can be a string or an array of strings.
  */
 type MicromatchPattern = string | string[];
+/**
+ * Configuration options for categorizing dependencies as external or local.
+ */
+type FlagAsExternalOptions = {
+    /** When true, non-relative dependencies whose path cannot be resolved are categorized as external (default: true) */
+    unresolvableAlias?: boolean;
+    /** When true, non-relative paths that include node_modules are categorized as external (default: true) */
+    inNodeModules?: boolean;
+    /** When true, dependencies whose resolved path is outside the configured root path are categorized as external (default: false) */
+    outsideRootPath?: boolean;
+    /** List of patterns (using micromatch syntax) that, when matching the source of the dependency, categorize it as external (default: []) */
+    customSourcePatterns?: string[];
+};
 /** Configuration options for the Config class */
 type ConfigOptions = {
     /** An array of path patterns to include when resolving elements. Defaults to all files if not specified */
@@ -15,15 +28,33 @@ type ConfigOptions = {
     legacyTemplates?: boolean;
     /** Whether to enable caching */
     cache?: boolean;
+    /** Configuration for categorizing dependencies as external or local */
+    flagAsExternal?: FlagAsExternalOptions;
+    /** Root path of the project, used for determining if dependencies are outside the project */
+    rootPath?: string;
+};
+type FlagAsExternalOptionsNormalized = {
+    /** When true, non-relative dependencies whose path cannot be resolved are categorized as external */
+    unresolvableAlias: boolean;
+    /** When true, non-relative paths that include node_modules are categorized as external */
+    inNodeModules: boolean;
+    /** When true, dependencies whose resolved path is outside the configured root path are categorized as external */
+    outsideRootPath: boolean;
+    /** List of patterns (using micromatch syntax) that, when matching the source of the dependency, categorize it as external */
+    customSourcePatterns: string[];
 };
-type ConfigOptionsNormalized = Omit<ConfigOptions, "legacyTemplates" | "cache"> & {
+type ConfigOptionsNormalized = Omit<ConfigOptions, "legacyTemplates" | "cache" | "flagAsExternal"> & {
     /** Whether to enable legacy template support */
     legacyTemplates: boolean;
     /** Cache configuration options */
     cache: boolean;
+    /** Configuration for categorizing dependencies as external or local */
+    flagAsExternal: FlagAsExternalOptionsNormalized;
+    /** Root path of the project, already normalized, and finishing with a slash, used for determining if dependencies are outside the project */
+    rootPath: string | undefined;
 };
 /** Options for descriptors */
-type DescriptorOptionsNormalized = Pick<ConfigOptionsNormalized, "includePaths" | "ignorePaths" | "cache">;
+type DescriptorOptionsNormalized = Pick<ConfigOptionsNormalized, "includePaths" | "ignorePaths" | "cache" | "flagAsExternal" | "rootPath">;
 /** Options for element matchers */
 type MatchersOptionsNormalized = Pick<ConfigOptionsNormalized, "legacyTemplates">;
 
@@ -1544,14 +1575,37 @@ declare class ElementsDescriptor {
      * @returns The base source of the external module. (e.g., for "@scope/package/submodule", it returns "@scope/package")
      */
     private _getExternalOrCoreModuleBaseSource;
+    /**
+     * Determines if a file path is outside the configured root path.
+     * @param filePath The file path to check.
+     * @returns True if the file path is outside the root path, false otherwise.
+     */
+    private _isOutsideRootPath;
+    /**
+     * Converts an absolute file path to a relative path if rootPath is configured.
+     * If rootPath is not configured, returns the path as-is (maintains backward compatibility).
+     * @param filePath The file path to convert (can be absolute or relative)
+     * @returns The relative path if rootPath is configured and path is absolute, otherwise the original path
+     */
+    private _toRelativePath;
+    /**
+     * Checks if a source string matches any of the provided patterns using micromatch.
+     * @param patterns - Array of micromatch patterns
+     * @param source - The source string to match against patterns
+     * @returns True if the source matches any pattern, false otherwise
+     */
+    private _matchesAnyPattern;
     /**
      * Determines if an element is external based on its file path and dependency source.
-     * Files inside "node_modules" are considered external.
-     * If the dependency source is not provided, only the file path is considered.
-     * If the dependency source is provided, it must not be a local path (i.e, it should start by "./", "../", or "/").
-     * @param filePath
-     * @param dependencySource
-     * @returns
+     * Uses the flagAsExternal configuration to evaluate multiple conditions with OR logic:
+     * - unresolvableAlias: Files whose path cannot be resolved (filePath is null)
+     * - inNodeModules: Non-relative paths that include "node_modules"
+     * - outsideRootPath: Resolved path is outside the configured root path (only if rootPath is configured)
+     * - customSourcePatterns: Source matches any of the configured patterns
+     * @param filePath The resolved file path (null if unresolved). Can be absolute if rootPath is configured, or relative if rootPath is not configured.
+     * @param isOutsideRootPath Whether the file path is outside the configured root path.
+     * @param dependencySource The import/export source string
+     * @returns True if any of the configured conditions is met, false otherwise
      */
     private _isExternalDependency;
     /**
@@ -1599,27 +1653,28 @@ declare class ElementsDescriptor {
     /**
      * Returns an external or core dependency element given its dependency source and file path.
      * @param dependencySource The source of the dependency.
-     * @param filePath The resolved file path of the dependency, if known.
+     * @param isOutsideRootPath Whether the file path is outside the configured root path.
+     * @param filePath The resolved file path of the dependency, if known. Can be absolute if rootPath is configured.
      * @returns The external or core dependency element, or null if it is a local dependency.
      */
     private _getExternalOrCoreDependencyElement;
     /**
      * Describes an element given its file path and dependency source, if any.
-     * @param filePath The path of the file to describe.
+     * @param filePath The path of the file to describe. Can be absolute if rootPath is configured, or relative if not.
      * @param dependencySource The source of the dependency, if the element to describe is so. It refers to the import/export path used to reference the file or external module.
      * @returns The description of the element. A dependency element if dependency source is provided, otherwise a file element.
      */
     private _describeElement;
     /**
      * Describes an element given its file path.
-     * @param filePath The path of the file to describe.
+     * @param filePath The path of the file to describe. Can be absolute if rootPath is configured, or relative if not.
      * @returns The description of the element.
      */
     describeElement(filePath?: string): FileElement;
     /**
      * Describes a dependency element given its dependency source and file path.
      * @param dependencySource The source of the dependency.
-     * @param filePath The path of the file being the dependency, if known.
+     * @param filePath The path of the file being the dependency, if known. Can be absolute if rootPath is configured, or relative if not.
      * @returns The description of the dependency element.
      */
     describeDependencyElement(dependencySource: string, filePath?: string): DependencyElementDescription;
@@ -1791,4 +1846,4 @@ declare class CacheManager<CacheKey extends NotUndefined, CachedValue> {
     setFromSerialized(serializedCache: Record<string, CachedValue>): void;
 }
 
-export { type BaseDependencyElement, type BaseElement, type BaseElementDescriptor, type BaseElementSelector, type BaseElementSelectorData, type BaseElementSelectorWithOptions, type BaseElementsSelector, CacheManager, type CapturedValues, type CapturedValuesSelector, type ConfigOptions, type ConfigOptionsNormalized, type CoreDependencyElement, DEPENDENCY_KINDS_MAP, DEPENDENCY_KIND_TYPE, DEPENDENCY_KIND_TYPEOF, DEPENDENCY_KIND_VALUE, DEPENDENCY_RELATIONSHIPS_INVERTED_MAP, DEPENDENCY_RELATIONSHIPS_MAP, DependenciesDescriptor, type DependenciesDescriptorSerializedCache, DependenciesMatcher, type DependenciesMatcherSerializedCache, type DependencyDescription, type DependencyElementDescription, type DependencyElementSelector, type DependencyElementSelectorData, type DependencyElementSelectorWithOptions, type DependencyElementsSelector, type DependencyKind, type DependencyMatchResult, type DependencyRelationship, type DependencySelector, type DependencySelectorNormalized, type DescribeDependencyOptions, type DescriptionsSerializedCache, type DescriptorOptionsNormalized, Descriptors, type DescriptorsSerializedCache, ELEMENT_DESCRIPTOR_MODES_MAP, ELEMENT_ORIGINS_MAP, type ElementDescription, type ElementDescriptor, type ElementDescriptorMode, type ElementDescriptorPattern, type ElementDescriptorWithCategory, type ElementDescriptorWithType, type ElementDescriptorWithTypeAndCategory, type ElementDescriptors, type ElementOrigin, type ElementParent, type ElementSelector, type ElementSelectorData, type ElementSelectorWithOptions, type ElementSelectors, Elements, type ElementsDependencyInfo, ElementsDescriptor, type ElementsDescriptorSerializedCache, ElementsMatcher, type ElementsMatcherSerializedCache, type ElementsSelector, type ElementsSerializedCache, type ExternalDependencyElement, type ExternalLibrariesSelector, type ExternalLibrarySelector, type ExternalLibrarySelectorOptions, type ExternalLibrarySelectorWithOptions, type ExternalLibrarySelectors, type FileElement, type FileElementsSerializedCache, type IgnoredDependencyElement, type IgnoredElement, type LocalDependencyElement, type LocalDependencyElementKnown, type LocalDependencyElementUnknown, type LocalElementKnown, type LocalElementUnknown, Matcher, type MatcherOptions, type MatcherOptionsDependencySelectorsGlobals, type MatcherSerializedCache, type MatchersOptionsNormalized, type MicromatchPattern, type MicromatchSerializedCache, type NotUndefined, type ObjectCacheKey, type SelectableElement, type SimpleElementSelectorByType, type TemplateData, isBaseElement, isBaseElementDescriptor, isBaseElementSelectorData, isCapturedValuesSelector, isCoreDependencyElement, isDependencyDescription, isDependencyElementDescription, isDependencyKind, isDependencyRelationship, isDependencyRelationshipDescription, isDependencySelector, isElementDescription, isElementDescriptor, isElementDescriptorMode, isElementDescriptorPattern, isElementDescriptorWithCategory, isElementDescriptorWithType, isElementSelector, isElementSelectorData, isElementSelectorWithLegacyOptions, isElementsDependencyInfo, isElementsSelector, isExternalDependencyElement, isExternalLibrariesSelector, isExternalLibrarySelector, isExternalLibrarySelectorOptions, isExternalLibrarySelectorOptionsWithPath, isExternalLibrarySelectorOptionsWithSpecifiers, isExternalLibrarySelectorWithOptions, isIgnoredElement, isInternalDependency, isKnownLocalElement, isLocalDependencyElement, isLocalElement, isSimpleElementSelectorByType, isUnknownLocalElement, normalizeElementsSelector };
+export { type BaseDependencyElement, type BaseElement, type BaseElementDescriptor, type BaseElementSelector, type BaseElementSelectorData, type BaseElementSelectorWithOptions, type BaseElementsSelector, CacheManager, type CapturedValues, type CapturedValuesSelector, type ConfigOptions, type ConfigOptionsNormalized, type CoreDependencyElement, DEPENDENCY_KINDS_MAP, DEPENDENCY_KIND_TYPE, DEPENDENCY_KIND_TYPEOF, DEPENDENCY_KIND_VALUE, DEPENDENCY_RELATIONSHIPS_INVERTED_MAP, DEPENDENCY_RELATIONSHIPS_MAP, DependenciesDescriptor, type DependenciesDescriptorSerializedCache, DependenciesMatcher, type DependenciesMatcherSerializedCache, type DependencyDescription, type DependencyElementDescription, type DependencyElementSelector, type DependencyElementSelectorData, type DependencyElementSelectorWithOptions, type DependencyElementsSelector, type DependencyKind, type DependencyMatchResult, type DependencyRelationship, type DependencySelector, type DependencySelectorNormalized, type DescribeDependencyOptions, type DescriptionsSerializedCache, type DescriptorOptionsNormalized, Descriptors, type DescriptorsSerializedCache, ELEMENT_DESCRIPTOR_MODES_MAP, ELEMENT_ORIGINS_MAP, type ElementDescription, type ElementDescriptor, type ElementDescriptorMode, type ElementDescriptorPattern, type ElementDescriptorWithCategory, type ElementDescriptorWithType, type ElementDescriptorWithTypeAndCategory, type ElementDescriptors, type ElementOrigin, type ElementParent, type ElementSelector, type ElementSelectorData, type ElementSelectorWithOptions, type ElementSelectors, Elements, type ElementsDependencyInfo, ElementsDescriptor, type ElementsDescriptorSerializedCache, ElementsMatcher, type ElementsMatcherSerializedCache, type ElementsSelector, type ElementsSerializedCache, type ExternalDependencyElement, type ExternalLibrariesSelector, type ExternalLibrarySelector, type ExternalLibrarySelectorOptions, type ExternalLibrarySelectorWithOptions, type ExternalLibrarySelectors, type FileElement, type FileElementsSerializedCache, type FlagAsExternalOptions, type FlagAsExternalOptionsNormalized, type IgnoredDependencyElement, type IgnoredElement, type LocalDependencyElement, type LocalDependencyElementKnown, type LocalDependencyElementUnknown, type LocalElementKnown, type LocalElementUnknown, Matcher, type MatcherOptions, type MatcherOptionsDependencySelectorsGlobals, type MatcherSerializedCache, type MatchersOptionsNormalized, type MicromatchPattern, type MicromatchSerializedCache, type NotUndefined, type ObjectCacheKey, type SelectableElement, type SimpleElementSelectorByType, type TemplateData, isBaseElement, isBaseElementDescriptor, isBaseElementSelectorData, isCapturedValuesSelector, isCoreDependencyElement, isDependencyDescription, isDependencyElementDescription, isDependencyKind, isDependencyRelationship, isDependencyRelationshipDescription, isDependencySelector, isElementDescription, isElementDescriptor, isElementDescriptorMode, isElementDescriptorPattern, isElementDescriptorWithCategory, isElementDescriptorWithType, isElementSelector, isElementSelectorData, isElementSelectorWithLegacyOptions, isElementsDependencyInfo, isElementsSelector, isExternalDependencyElement, isExternalLibrariesSelector, isExternalLibrarySelector, isExternalLibrarySelectorOptions, isExternalLibrarySelectorOptionsWithPath, isExternalLibrarySelectorOptionsWithSpecifiers, isExternalLibrarySelectorWithOptions, isIgnoredElement, isInternalDependency, isKnownLocalElement, isLocalDependencyElement, isLocalElement, isSimpleElementSelectorByType, isUnknownLocalElement, normalizeElementsSelector };