@boundaries/elements 1.1.2 → 1.2.0

package/dist/index.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.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 };

package/dist/index.js

@@ -80,6 +80,46 @@ __export(src_exports, {
 });
 module.exports = __toCommonJS(src_exports);
 
+// src/Support/TypeGuards.ts
+function isString(value) {
+  return typeof value === "string";
+}
+function isNullish(value) {
+  return value === null || value === void 0;
+}
+function isNull(value) {
+  return value === null;
+}
+function isBoolean(value) {
+  return typeof value === "boolean";
+}
+function isObject(value) {
+  return !isNullish(value) && !isBoolean(value) && !isArray(value) && typeof value === "object";
+}
+function isEmptyObject(obj) {
+  return isObject(obj) && Object.keys(obj).length === 0;
+}
+function isArray(value) {
+  return Array.isArray(value);
+}
+function isEmptyArray(arr) {
+  return arr.length === 0;
+}
+function isStringArray(value) {
+  return isArray(value) && value.every(isString);
+}
+function isObjectWithProperty(value, key) {
+  return isObject(value) && Object.hasOwn(value, key);
+}
+function isObjectWithAnyOfProperties(value, keys) {
+  return isObject(value) && keys.some((key) => key in value);
+}
+
+// src/Support/Paths.ts
+function normalizePath(filePath) {
+  return filePath.replaceAll("\\", "/");
+}
+
 // src/Config/Config.ts
 var Config = class {
   /** The ignore paths */
@@ -90,6 +130,10 @@ var Config = class {
   _legacyTemplates;
   /** Whether the cache is enabled */
   _cache;
+  /** Configuration for categorizing dependencies as external or local */
+  _flagAsExternal;
+  /** Root path of the project */
+  _rootPath;
   /**
    * Creates a new Config instance
    * @param options Configuration options
@@ -99,6 +143,18 @@ var Config = class {
     this._includePaths = options?.includePaths;
     this._legacyTemplates = options?.legacyTemplates ?? true;
     this._cache = options?.cache ?? true;
+    this._flagAsExternal = {
+      unresolvableAlias: options?.flagAsExternal?.unresolvableAlias ?? true,
+      inNodeModules: options?.flagAsExternal?.inNodeModules ?? true,
+      outsideRootPath: options?.flagAsExternal?.outsideRootPath ?? false,
+      customSourcePatterns: options?.flagAsExternal?.customSourcePatterns ?? []
+    };
+    if (options?.rootPath) {
+      const normalizedRoot = normalizePath(options.rootPath);
+      this._rootPath = normalizedRoot.endsWith("/") ? normalizedRoot : `${normalizedRoot}/`;
+    } else {
+      this._rootPath = void 0;
+    }
   }
   /**
    * The normalized configuration options
@@ -108,7 +164,9 @@ var Config = class {
       ignorePaths: this._ignorePaths,
       includePaths: this._includePaths,
       legacyTemplates: this._legacyTemplates,
-      cache: this._cache
+      cache: this._cache,
+      flagAsExternal: this._flagAsExternal,
+      rootPath: this._rootPath
     };
   }
   /**
@@ -118,7 +176,9 @@ var Config = class {
     return {
       ignorePaths: this._ignorePaths,
       includePaths: this._includePaths,
-      cache: this._cache
+      cache: this._cache,
+      flagAsExternal: this._flagAsExternal,
+      rootPath: this._rootPath
     };
   }
   /**
@@ -140,41 +200,6 @@ var Config = class {
 // src/Matcher/BaseElementsMatcher.ts
 var import_handlebars = __toESM(require("handlebars"));
 
-// src/Support/TypeGuards.ts
-function isString(value) {
-  return typeof value === "string";
-}
-function isNullish(value) {
-  return value === null || value === void 0;
-}
-function isNull(value) {
-  return value === null;
-}
-function isBoolean(value) {
-  return typeof value === "boolean";
-}
-function isObject(value) {
-  return !isNullish(value) && !isBoolean(value) && !isArray(value) && typeof value === "object";
-}
-function isEmptyObject(obj) {
-  return isObject(obj) && Object.keys(obj).length === 0;
-}
-function isArray(value) {
-  return Array.isArray(value);
-}
-function isEmptyArray(arr) {
-  return arr.length === 0;
-}
-function isStringArray(value) {
-  return isArray(value) && value.every(isString);
-}
-function isObjectWithProperty(value, key) {
-  return isObject(value) && Object.hasOwn(value, key);
-}
-function isObjectWithAnyOfProperties(value, keys) {
-  return isObject(value) && keys.some((key) => key in value);
-}
-
 // src/Matcher/MatcherHelpers.ts
 function isCapturedValuesSelector(value) {
   if (!isObject(value) || isArray(value)) {
@@ -1605,17 +1630,72 @@ var ElementsDescriptor = class {
     return pkg;
   }
   /**
-   * 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
+   * 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.
+   */
+  _isOutsideRootPath(filePath) {
+    if (!this._config.rootPath) {
+      return false;
+    }
+    return !filePath.startsWith(this._config.rootPath);
+  }
+  /**
+   * 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
+   */
+  _toRelativePath(filePath) {
+    if (!this._config.rootPath || this._isOutsideRootPath(filePath)) {
+      return filePath;
+    }
+    return filePath.replace(this._config.rootPath, "");
+  }
+  /**
+   * 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
    */
-  _isExternalDependency(filePath, dependencySource) {
-    return (!filePath || filePath.includes("node_modules")) && // Not having a source, and being in node_modules only could happen if user is analyzing a file directly from there, not as a dependency. Should this be considered external then?
-    (!dependencySource || this._dependencySourceIsExternalOrScoped(dependencySource));
+  _matchesAnyPattern(patterns, source) {
+    if (!source || patterns.length === 0) {
+      return false;
+    }
+    return this._micromatch.isMatch(source, patterns);
+  }
+  /**
+   * Determines if an element is external based on its file path and dependency source.
+   * 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
+   */
+  _isExternalDependency(filePath, isOutsideRootPath, dependencySource) {
+    const {
+      unresolvableAlias,
+      inNodeModules,
+      outsideRootPath,
+      customSourcePatterns
+    } = this._config.flagAsExternal;
+    if (outsideRootPath && isOutsideRootPath) {
+      return true;
+    }
+    if (inNodeModules && filePath?.includes("node_modules")) {
+      return true;
+    }
+    if (unresolvableAlias && !filePath && dependencySource && this._dependencySourceIsExternalOrScoped(dependencySource)) {
+      return true;
+    }
+    if (this._matchesAnyPattern(customSourcePatterns, dependencySource)) {
+      return true;
+    }
+    return false;
   }
   /**
    * Determines if a given path is included based on the configuration.
@@ -1683,6 +1763,16 @@ var ElementsDescriptor = class {
     }
     return `${[...allPathSegments].reverse().join("/").split(result)[0]}${result}`;
   }
+  /**
+   * Determines if an element descriptor matches the given parameters in the provided path.
+   * @param options The options for matching the descriptor.
+   * @param options.elementDescriptor The element descriptor to match.
+   * @param options.filePath The file path to match against the descriptor.
+   * @param options.currentPathSegments The current path segments leading to the element.
+   * @param options.lastPathSegmentMatching The last path segment that was matched.
+   * @param options.alreadyMatched Whether the element matched previously.
+   * @returns The result of the match, including whether it matched.
+   */
   _fileDescriptorMatch({
     elementDescriptor,
     filePath,
@@ -1837,10 +1927,11 @@ var ElementsDescriptor = class {
   /**
    * 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.
    */
-  _getExternalOrCoreDependencyElement(dependencySource, filePath) {
+  _getExternalOrCoreDependencyElement(dependencySource, isOutsideRootPath, filePath) {
     const baseDependencySource = this._getExternalOrCoreModuleBaseSource(dependencySource);
     const isCore = this._dependencySourceIsCoreModule(
       dependencySource,
@@ -1857,6 +1948,7 @@ var ElementsDescriptor = class {
     }
     const isExternal = this._isExternalDependency(
       filePath || null,
+      isOutsideRootPath,
       dependencySource
     );
     if (isExternal) {
@@ -1877,12 +1969,19 @@ var ElementsDescriptor = class {
     if (this._descriptionsCache.has(cacheKey)) {
       return this._descriptionsCache.get(cacheKey);
     }
-    const externalOrCoreDependencyElement = dependencySource ? this._getExternalOrCoreDependencyElement(dependencySource, filePath) : null;
+    const normalizedFilePath = filePath ? normalizePath(filePath) : filePath;
+    const isOutsideRootPath = normalizedFilePath ? this._isOutsideRootPath(normalizedFilePath) : false;
+    const relativePath = normalizedFilePath && this._config.rootPath ? this._toRelativePath(normalizedFilePath) : normalizedFilePath;
+    const externalOrCoreDependencyElement = dependencySource ? this._getExternalOrCoreDependencyElement(
+      dependencySource,
+      isOutsideRootPath,
+      relativePath
+    ) : null;
     if (externalOrCoreDependencyElement) {
       this._descriptionsCache.set(cacheKey, externalOrCoreDependencyElement);
       return externalOrCoreDependencyElement;
     }
-    const fileDescription = this._describeFile(filePath);
+    const fileDescription = this._describeFile(relativePath);
     const elementResult = dependencySource ? {
       ...fileDescription,
       source: dependencySource
@@ -1892,7 +1991,7 @@ var ElementsDescriptor = class {
   }
   /**
    * 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) {
@@ -1901,7 +2000,7 @@ var ElementsDescriptor = class {
   /**
    * 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, filePath) {
@@ -2289,7 +2388,7 @@ var MatchersCache = class extends CacheManager {
     config,
     elementDescriptors
   }) {
-    const configHash = `${config.legacyTemplates}|${config.includePaths}|${config.ignorePaths}|${config.cache}`;
+    const configHash = `${config.legacyTemplates}|${config.includePaths}|${config.ignorePaths}|${config.cache}|${config.rootPath}|${config.flagAsExternal.inNodeModules}|${config.flagAsExternal.unresolvableAlias}|${config.flagAsExternal.outsideRootPath}|${config.flagAsExternal.customSourcePatterns.join(",")}`;
     const elementDescriptorsHash = elementDescriptors.map(
       (descriptor) => `${descriptor.type}|${descriptor.category}|${descriptor.pattern}|${descriptor.basePattern}|${descriptor.mode}|${descriptor.capture}|${descriptor.baseCapture}`
     ).join(",");