@boundaries/elements 1.1.2 → 1.2.0

package/dist/index.mjs

@@ -5,6 +5,46 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 
+// 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 */
@@ -15,6 +55,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
@@ -24,6 +68,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
@@ -33,7 +89,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
     };
   }
   /**
@@ -43,7 +101,9 @@ var Config = class {
     return {
       ignorePaths: this._ignorePaths,
       includePaths: this._includePaths,
-      cache: this._cache
+      cache: this._cache,
+      flagAsExternal: this._flagAsExternal,
+      rootPath: this._rootPath
     };
   }
   /**
@@ -65,41 +125,6 @@ var Config = class {
 // src/Matcher/BaseElementsMatcher.ts
 import Handlebars from "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)) {
@@ -1530,17 +1555,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.
@@ -1608,6 +1688,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,
@@ -1762,10 +1852,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,
@@ -1782,6 +1873,7 @@ var ElementsDescriptor = class {
     }
     const isExternal = this._isExternalDependency(
       filePath || null,
+      isOutsideRootPath,
       dependencySource
     );
     if (isExternal) {
@@ -1802,12 +1894,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
@@ -1817,7 +1916,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) {
@@ -1826,7 +1925,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) {
@@ -2214,7 +2313,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(",");