@boundaries/elements 1.2.0 → 2.0.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -2,6 +2,10 @@
2
2
  * Type representing a micromatch pattern, which can be a string or an array of strings.
3
3
  */
4
4
  type MicromatchPattern = string | string[];
5
+ /**
6
+ * Type representing a micromatch pattern supporting null values
7
+ */
8
+ type MicromatchPatternNullable = string | null | (string | null)[];
5
9
  /**
6
10
  * Configuration options for categorizing dependencies as external or local.
7
11
  */
@@ -150,14 +154,17 @@ type ElementDescriptor = ElementDescriptorWithType | ElementDescriptorWithCatego
150
154
  * Array of element descriptors.
151
155
  */
152
156
  type ElementDescriptors = ElementDescriptor[];
157
+ type ElementDescriptionWithSource = ElementDescription & {
158
+ module?: string | null;
159
+ };
153
160
  /**
154
161
  * Serialized cache of element descriptions.
155
162
  */
156
- type DescriptionsSerializedCache = Record<string, ElementDescription>;
163
+ type DescriptionsSerializedCache = Record<string, ElementDescription | ElementDescriptionWithSource>;
157
164
  /**
158
165
  * Serialized cache of file elements.
159
166
  */
160
- type FileElementsSerializedCache = Record<string, FileElement>;
167
+ type FileElementsSerializedCache = Record<string, ElementDescription>;
161
168
  /**
162
169
  * Serialized cache for ElementsDescriptor class.
163
170
  */
@@ -189,17 +196,13 @@ type ElementOrigin = (typeof ELEMENT_ORIGINS_MAP)[keyof typeof ELEMENT_ORIGINS_M
189
196
  /**
190
197
  * Base element properties related to captured values
191
198
  */
192
- type BaseElement = {
199
+ type BaseElementDescription = {
193
200
  /** Absolute path of the file. It might be null when a dependency path can't be resolved */
194
201
  path: string | null;
195
202
  /** Path of the file relative to the element, or null if the element is ignored or unknown */
196
203
  elementPath: string | null;
197
204
  /** Internal path of the file relative to the elementPath, or null if the element is ignored or unknown */
198
205
  internalPath: string | null;
199
- /** Source of the element when it is a dependency, or null if the element is not a dependency, or it is ignored or unknown */
200
- source: string | null;
201
- /** Base source of the element when it is an external or core dependency, null otherwise */
202
- baseSource: string | null;
203
206
  /** Type of the element, or null if the element is ignored or unknown */
204
207
  type: string | null;
205
208
  /** Category of the element, or null if the element is ignored or unknown */
@@ -231,7 +234,7 @@ type ElementParent = {
231
234
  /**
232
235
  * Description of an ignored element
233
236
  */
234
- type IgnoredElement = BaseElement & {
237
+ type IgnoredElement = BaseElementDescription & {
235
238
  /** Type of the element */
236
239
  type: null;
237
240
  /** Category of the element */
@@ -248,7 +251,7 @@ type IgnoredElement = BaseElement & {
248
251
  /**
249
252
  * Description of an unknown local element
250
253
  */
251
- type LocalElementUnknown = BaseElement & {
254
+ type LocalElementUnknown = BaseElementDescription & {
252
255
  /** Type of the element */
253
256
  type: null;
254
257
  /** Category of the element */
@@ -265,7 +268,7 @@ type LocalElementUnknown = BaseElement & {
265
268
  /**
266
269
  * Description of a local element (file)
267
270
  */
268
- type LocalElementKnown = BaseElement & {
271
+ type LocalElementKnown = BaseElementDescription & {
269
272
  /** Path of the element */
270
273
  path: string;
271
274
  /** Captured values from the parent element */
@@ -284,65 +287,23 @@ type LocalElementKnown = BaseElement & {
284
287
  isUnknown: false;
285
288
  };
286
289
  /**
287
- * Base description of a dependency
288
- */
289
- type BaseDependencyElement = BaseElement & {
290
- /** Dependency source */
291
- source: string;
292
- /** Indicates that dependencies are not ignored */
293
- isIgnored: false;
294
- };
295
- /**
296
- * Description of a local dependency (known)
297
- */
298
- type LocalDependencyElementKnown = LocalElementKnown & BaseDependencyElement;
299
- /**
300
- * Description of a local dependency (unknown)
301
- */
302
- type LocalDependencyElementUnknown = LocalElementUnknown & BaseDependencyElement;
303
- /**
304
- * Description of a local dependency
290
+ * Description of an unknown external element.
305
291
  */
306
- type LocalDependencyElement = LocalDependencyElementKnown | LocalDependencyElementUnknown;
307
- /**
308
- * Description of an external dependency
309
- */
310
- type ExternalDependencyElement = BaseDependencyElement & {
311
- /** Path of the dependency relative to the base module */
312
- internalPath: string;
313
- /** Base module of the external dependency */
314
- baseSource: string;
315
- /** Indicates that the dependency is external */
292
+ type ExternalElementDescription = BaseElementDescription & {
316
293
  origin: typeof ELEMENT_ORIGINS_MAP.EXTERNAL;
294
+ isIgnored: false;
317
295
  };
318
296
  /**
319
- * Description of a core dependency
297
+ * Description of an unknown core element.
320
298
  */
321
- type CoreDependencyElement = BaseDependencyElement & {
322
- /** Base module of the core dependency */
323
- baseSource: string;
324
- /** Indicates that the dependency is core */
299
+ type CoreElementDescription = BaseElementDescription & {
325
300
  origin: typeof ELEMENT_ORIGINS_MAP.CORE;
301
+ isIgnored: false;
326
302
  };
327
- /**
328
- * Description of an ignored dependency element
329
- */
330
- type IgnoredDependencyElement = IgnoredElement & {
331
- /** The source of the dependency */
332
- source: string;
333
- };
334
- /**
335
- * Description of a file
336
- */
337
- type FileElement = IgnoredElement | LocalElementKnown | LocalElementUnknown;
338
- /**
339
- * Description of a dependency
340
- */
341
- type DependencyElementDescription = IgnoredDependencyElement | CoreDependencyElement | LocalDependencyElement | ExternalDependencyElement;
342
303
  /**
343
304
  * Description of an element, either local or dependency
344
305
  */
345
- type ElementDescription = FileElement | DependencyElementDescription;
306
+ type ElementDescription = LocalElementKnown | LocalElementUnknown | IgnoredElement | ExternalElementDescription | CoreElementDescription;
346
307
 
347
308
  /**
348
309
  * Determines if the given value is a valid element descriptor mode.
@@ -385,7 +346,7 @@ declare function isElementDescriptor(value: unknown): value is ElementDescriptor
385
346
  * @param value The value to check
386
347
  * @returns True if the value is a valid BaseElement, false otherwise
387
348
  */
388
- declare function isBaseElement(value: unknown): value is BaseElement;
349
+ declare function isBaseElement(value: unknown): value is BaseElementDescription;
389
350
  /**
390
351
  * Determines if the given value is an ignored element.
391
352
  * @param value The element to check.
@@ -410,36 +371,30 @@ declare function isUnknownLocalElement(value: unknown): value is LocalElementUnk
410
371
  * @returns True if the element is an unknown element, false otherwise.
411
372
  */
412
373
  declare function isKnownLocalElement(value: unknown): value is LocalElementKnown;
413
- /**
414
- * Determines if the given value is a dependency element.
415
- * @param value The element to check.
416
- * @returns True if the element is a dependency element, false otherwise.
417
- */
418
- declare function isDependencyElementDescription(value: unknown): value is DependencyElementDescription;
419
- /**
420
- * Determines if the given value is an element (local or dependency).
421
- * @param value The value to check.
422
- * @returns True if the value is an element, false otherwise.
423
- */
424
- declare function isElementDescription(value: unknown): value is ElementDescription;
425
374
  /**
426
375
  * Determines if the given value is a local dependency element.
427
376
  * @param value The value to check.
428
377
  * @returns True if the element is a local dependency element, false otherwise.
429
378
  */
430
- declare function isLocalDependencyElement(value: unknown): value is LocalDependencyElement;
379
+ declare function isLocalDependencyElement(value: unknown): value is LocalElementKnown | LocalElementUnknown;
431
380
  /**
432
381
  * Determines if the given value is an external element.
433
382
  * @param value The value to check.
434
383
  * @returns True if the element is an external dependency element, false otherwise.
435
384
  */
436
- declare function isExternalDependencyElement(value: unknown): value is ExternalDependencyElement;
385
+ declare function isExternalDependencyElement(value: unknown): value is ElementDescription;
437
386
  /**
438
387
  * Determines if the given value is a core element.
439
388
  * @param value The value to check.
440
389
  * @returns True if the element is a core dependency element, false otherwise.
441
390
  */
442
- declare function isCoreDependencyElement(value: unknown): value is CoreDependencyElement;
391
+ declare function isCoreDependencyElement(value: unknown): value is ElementDescription;
392
+ /**
393
+ * Determines if the given value is an element (local or dependency).
394
+ * @param value The value to check.
395
+ * @returns True if the value is an element, false otherwise.
396
+ */
397
+ declare function isElementDescription(value: unknown): value is ElementDescription;
443
398
 
444
399
  declare const DEPENDENCY_KIND_TYPE: "type";
445
400
  declare const DEPENDENCY_KIND_VALUE: "value";
@@ -488,6 +443,10 @@ declare const DEPENDENCY_RELATIONSHIPS_INVERTED_MAP: {
488
443
  type DependencyRelationship = (typeof DEPENDENCY_RELATIONSHIPS_MAP)[keyof typeof DEPENDENCY_RELATIONSHIPS_MAP];
489
444
  /** Information about a dependency between two elements */
490
445
  type ElementsDependencyInfo = {
446
+ /** Source of the dependency (import/export path) */
447
+ source: string;
448
+ /** Base source of the dependency for external/core modules */
449
+ module: string | null;
491
450
  /** Kind of the dependency */
492
451
  kind: DependencyKind;
493
452
  /** Type of the node creating the dependency in the dependent element */
@@ -507,9 +466,9 @@ type ElementsDependencyInfo = {
507
466
  */
508
467
  type DependencyDescription = {
509
468
  /** Source element of the dependency */
510
- from: FileElement;
469
+ from: ElementDescription;
511
470
  /** Target element of the dependency */
512
- to: DependencyElementDescription;
471
+ to: ElementDescription;
513
472
  /** Information about the dependency */
514
473
  dependency: ElementsDependencyInfo;
515
474
  };
@@ -585,16 +544,18 @@ type DescriptorsSerializedCache = {
585
544
  */
586
545
  type DependencyMatchResult = {
587
546
  /** The selector matching result for the 'from' element. */
588
- from: ElementSelectorData | null;
547
+ from: BaseElementSelectorData | null;
589
548
  /** The selector matching result for the 'to' element. */
590
- to: ElementSelectorData | null;
549
+ to: BaseElementSelectorData | null;
550
+ /** The selector matching result for the dependency metadata. */
551
+ dependency: DependencyDataSelectorData | null;
591
552
  /** Whether the dependency matches all the selector properties provided */
592
553
  isMatch: boolean;
593
554
  };
594
555
  /**
595
556
  * Serialized cache of elements matcher.
596
557
  */
597
- type ElementsMatcherSerializedCache = Record<string, ElementSelectorData | null>;
558
+ type ElementsMatcherSerializedCache = Record<string, BaseElementSelectorData | null>;
598
559
  /**
599
560
  * Serialized cache of dependencies matcher.
600
561
  */
@@ -615,34 +576,36 @@ type MicromatchSerializedCache = {
615
576
  /**
616
577
  * Elements that can return a match when using an element selector.
617
578
  */
618
- type SelectableElement = IgnoredElement | LocalElementKnown | LocalElementUnknown | CoreDependencyElement | ExternalDependencyElement | LocalDependencyElementKnown;
579
+ type SelectableElement = ElementDescription;
619
580
  /**
620
581
  * Selector for matching captured values in element selectors.
621
582
  * It is a record where the keys are the names of the captured values and the values are the patterns to match on those captured values.
583
+ * When provided as an array, each element in the array represents an alternative (OR logic) - the selector matches if any of the array elements matches.
622
584
  */
623
- type CapturedValuesSelector = Record<string, MicromatchPattern>;
585
+ type CapturedValuesSelector = Record<string, MicromatchPatternNullable> | Array<Record<string, MicromatchPatternNullable>>;
624
586
  /**
625
- * Data to pass to selector templates when they are rendered before matching.
587
+ * Selector for matching the first parent element.
626
588
  */
627
- type TemplateData = Record<string, unknown>;
589
+ type ParentElementSelectorData = {
590
+ /** Type of the first parent element */
591
+ type?: MicromatchPatternNullable;
592
+ /** Category of the first parent element */
593
+ category?: MicromatchPatternNullable;
594
+ /** Path of the first parent element */
595
+ elementPath?: MicromatchPatternNullable;
596
+ /** Captured values from the first parent element */
597
+ captured?: CapturedValuesSelector;
598
+ };
628
599
  /**
629
- * Options for elements and dependencies matchers.
600
+ * Data to pass to selector templates when they are rendered before matching.
630
601
  */
631
- type MatcherOptionsDependencySelectorsGlobals = {
632
- /** The kind of the dependency */
633
- kind?: MicromatchPattern;
634
- };
602
+ type TemplateData = Record<string, unknown>;
635
603
  /**
636
604
  * Options for elements and dependencies matchers.
637
605
  */
638
606
  type MatcherOptions = {
639
607
  /** Extra data to pass to captured values templates. By default, data from the element and dependency being matched is passed as to/from. */
640
608
  extraTemplateData?: TemplateData;
641
- /**
642
- * Properties to add to all dependency selectors used in the matcher. Added for backwards compatibility, because eslint-plugin rules defined importKind at the top level of the rule options.
643
- * @deprecated Use 'kind' property directly in the dependency element selectors instead.
644
- **/
645
- dependencySelectorsGlobals?: MatcherOptionsDependencySelectorsGlobals;
646
609
  };
647
610
  /**
648
611
  * Simple element selector by type, represented as a string matching the element type.
@@ -654,40 +617,47 @@ type SimpleElementSelectorByType = string;
654
617
  */
655
618
  type BaseElementSelectorData = {
656
619
  /** Micromatch pattern(s) to match the path of the element */
657
- path?: MicromatchPattern;
620
+ path?: MicromatchPatternNullable;
658
621
  /** Micromatch pattern(s) to match the path of the element containing the file */
659
- elementPath?: MicromatchPattern;
622
+ elementPath?: MicromatchPatternNullable;
660
623
  /** Micromatch pattern(s) to match internal paths within the file or dependency, relative to the element path */
661
- internalPath?: MicromatchPattern;
624
+ internalPath?: MicromatchPatternNullable;
662
625
  /** Type of the element */
663
- type?: MicromatchPattern;
626
+ type?: MicromatchPatternNullable;
664
627
  /** Category of the element */
665
- category?: MicromatchPattern;
628
+ category?: MicromatchPatternNullable;
666
629
  /** Captured values selector for dynamic matching */
667
630
  captured?: CapturedValuesSelector;
631
+ /** Selector for matching the first parent element */
632
+ parent?: ParentElementSelectorData | null;
668
633
  /** Origin of the element */
669
- origin?: MicromatchPattern;
670
- /** Micromatch pattern(s) to match the source of the dependency */
671
- source?: MicromatchPattern;
672
- /** Base source of the element, e.g., the import path of a dependency */
673
- baseSource?: MicromatchPattern;
634
+ origin?: MicromatchPatternNullable;
674
635
  /** Whether the element is ignored */
675
636
  isIgnored?: boolean;
676
637
  /** Whether the element is unknown */
677
638
  isUnknown?: boolean;
678
639
  };
679
640
  /**
680
- * Selector for dependency elements, including kind, specifier, and node kind filters.
641
+ * Selector for dependency metadata.
681
642
  */
682
- type DependencyElementSelectorData = BaseElementSelectorData & {
683
- /** Relationship of the file element with the dependency declared in it */
684
- relationship?: MicromatchPattern;
643
+ type DependencyDataSelectorData = {
644
+ /** Relationship between both elements, from both perspectives */
645
+ relationship?: {
646
+ /** Relationship from dependant element perspective */
647
+ from?: MicromatchPatternNullable;
648
+ /** Relationship from dependency element perspective */
649
+ to?: MicromatchPatternNullable;
650
+ };
685
651
  /** Dependency kind to filter elements */
686
- kind?: MicromatchPattern;
652
+ kind?: MicromatchPatternNullable;
687
653
  /** Micromatch pattern(s) to match only specific imports/exports */
688
- specifiers?: MicromatchPattern;
654
+ specifiers?: MicromatchPatternNullable;
689
655
  /** Node kind to filter elements */
690
- nodeKind?: MicromatchPattern;
656
+ nodeKind?: MicromatchPatternNullable;
657
+ /** Dependency source used in import/export statements */
658
+ source?: MicromatchPatternNullable;
659
+ /** Base source of the dependency for external/core modules */
660
+ module?: MicromatchPatternNullable;
691
661
  };
692
662
  /**
693
663
  * File Element selector with options, including captured values for dynamic matching.
@@ -699,32 +669,16 @@ type BaseElementSelectorWithOptions = [
699
669
  SimpleElementSelectorByType,
700
670
  CapturedValuesSelector
701
671
  ];
702
- /**
703
- * Dependency Element selector with options, including captured values for dynamic matching.
704
- * It is represented as a tuple where the first element is the element type (string)
705
- * and the second element is an object containing a selector for captured values.
706
- * @deprecated Use DependencyElementSelectorData defining an object with type and/or category and the rest of properties directly instead.
707
- */
708
- type DependencyElementSelectorWithOptions = [
709
- SimpleElementSelectorByType,
710
- CapturedValuesSelector
711
- ];
712
672
  /**
713
673
  * Base Element selector, which can be a simple string, object with type and/or category, or a base element selector with options.
714
674
  */
715
675
  type BaseElementSelector = SimpleElementSelectorByType | BaseElementSelectorData | BaseElementSelectorWithOptions;
716
676
  /**
717
- * Dependency Element selector, which can be a simple string, object with type and/or category, or a dependency element selector with options.
677
+ * Base elements selector, which can be a single base element selector or an array of base element selectors.
718
678
  */
719
- type DependencyElementSelector = SimpleElementSelectorByType | DependencyElementSelectorData | DependencyElementSelectorWithOptions;
720
- /** Base elements selector, which can be a single base element selector or an array of base element selectors. */
721
679
  type BaseElementsSelector = BaseElementSelector | BaseElementSelector[];
722
- /** Dependency elements selector, which can be a single dependency element selector or an array of dependency element selectors. */
723
- type DependencyElementsSelector = DependencyElementSelector | DependencyElementSelector[];
724
- /**
725
- * Element selector data, which may be a base element selector or a dependency element selector.
726
- */
727
- type ElementSelectorData = BaseElementSelectorData | DependencyElementSelectorData;
680
+ /** Dependency metadata selector, which can be a single selector or an array of selectors. */
681
+ type DependencyDataSelector = DependencyDataSelectorData | DependencyDataSelectorData[];
728
682
  /**
729
683
  * Generic Element selector with options, including captured values for dynamic matching.
730
684
  * It is represented as a tuple where the first element is the element type (string)
@@ -738,11 +692,11 @@ type ElementSelectorWithOptions = [
738
692
  /**
739
693
  * Element selector, which can be a simple string, object with type and/or category, or an element selector with options.
740
694
  */
741
- type ElementSelector = SimpleElementSelectorByType | ElementSelectorData | ElementSelectorWithOptions;
695
+ type ElementSelector = SimpleElementSelectorByType | BaseElementSelectorData | ElementSelectorWithOptions;
742
696
  /**
743
697
  * Elements selector, which can be a single element selector or an array of element selectors.
744
698
  */
745
- type ElementsSelector = BaseElementsSelector | DependencyElementsSelector;
699
+ type ElementsSelector = BaseElementsSelector;
746
700
  /**
747
701
  * Element selectors, which can be a single element selector or an array of element selectors.
748
702
  * @deprecated Use ElementsSelector instead.
@@ -755,7 +709,9 @@ type DependencySelector = {
755
709
  /** Selector for the dependant elements. The file originating the dependency */
756
710
  from?: BaseElementsSelector;
757
711
  /** Selector for the dependency elements. The element being imported/exported */
758
- to?: DependencyElementsSelector;
712
+ to?: BaseElementsSelector;
713
+ /** Selector for dependency metadata */
714
+ dependency?: DependencyDataSelector;
759
715
  };
760
716
  /**
761
717
  * Normalized dependency selector, where 'from' and 'to' are always arrays or null.
@@ -764,40 +720,14 @@ type DependencySelectorNormalized = {
764
720
  /** Selector for the dependant elements. The file originating the dependency */
765
721
  from: BaseElementSelectorData[] | null;
766
722
  /** Selector for the dependency elements. The element being imported/exported */
767
- to: DependencyElementSelectorData[] | null;
768
- };
769
- /**
770
- * Options for selecting external libraries, including path patterns and optional specifiers.
771
- * If specifiers are provided, they will be used to match specific imports from the external library.
772
- */
773
- type ExternalLibrarySelectorOptions = {
774
- /**
775
- * Micromatch pattern(s) to match only one or more specific subpaths of the external library.
776
- */
777
- path?: MicromatchPattern;
778
- /** Micromatch pattern(s) to match only specific imports/exports */
779
- specifiers?: string[];
723
+ to: BaseElementSelectorData[] | null;
724
+ /** Selector for dependency metadata */
725
+ dependency: DependencyDataSelectorData[] | null;
780
726
  };
781
727
  /**
782
- * External library selector with options, represented as a tuple where the first element is the import path of the external library, and the second element is an object containing options for selecting only specific paths or specifiers from that library.
783
- */
784
- type ExternalLibrarySelectorWithOptions = [
785
- SimpleElementSelectorByType,
786
- ExternalLibrarySelectorOptions
787
- ];
788
- /**
789
- * External library selector, which can be a simple string (the import path) or an external library selector with options.
728
+ * @deprecated Use DependencySelectorDependencyData instead.
790
729
  */
791
- type ExternalLibrarySelector = SimpleElementSelectorByType | ExternalLibrarySelectorWithOptions;
792
- /**
793
- * External library selectors, which can be a single external library selector or an array of external library selectors.
794
- * @deprecated Use ExternalLibrariesSelector instead.
795
- */
796
- type ExternalLibrarySelectors = ExternalLibrariesSelector;
797
- /**
798
- * External libraries selector, which can be a single external library selector or an array of external library selectors.
799
- */
800
- type ExternalLibrariesSelector = ExternalLibrarySelector | ExternalLibrarySelector[];
730
+ type DependencyElementSelectorData = DependencyDataSelectorData;
801
731
 
802
732
  /**
803
733
  * Micromatch wrapper class with caching capabilities.
@@ -856,13 +786,6 @@ declare class Micromatch {
856
786
  makeRe(pattern: string): RegExp;
857
787
  }
858
788
 
859
- /**
860
- * Normalizes an ElementsSelector into an array of ElementSelectorData.
861
- * @param elementsSelector The elements selector, in any supported format.
862
- * @returns The normalized array of selector data.
863
- */
864
- declare function normalizeElementsSelector(elementsSelector: BaseElementsSelector): BaseElementSelectorData[];
865
- declare function normalizeElementsSelector(elementsSelector: DependencyElementsSelector): DependencyElementSelectorData[];
866
789
  /**
867
790
  * Base matcher class to determine if elements or dependencies match a given selector.
868
791
  */
@@ -907,7 +830,13 @@ declare class BaseElementsMatcher {
907
830
  * @param extraTemplateData The data to use for replace in the templates.
908
831
  * @returns The rendered templates.
909
832
  */
910
- protected getRenderedTemplates(template: MicromatchPattern, templateData: TemplateData): MicromatchPattern;
833
+ protected getRenderedTemplates(template: MicromatchPatternNullable, templateData: TemplateData): MicromatchPatternNullable;
834
+ /**
835
+ * Cleans a micromatch pattern by removing falsy values from arrays.
836
+ * @param pattern The micromatch pattern(s) to clean.
837
+ * @returns The cleaned pattern. If an array is provided, falsy entries are removed and the resulting array may be empty. If null is provided, null is returned unchanged.
838
+ */
839
+ protected cleanMicromatchPattern(pattern: MicromatchPatternNullable): string | string[] | null;
911
840
  /**
912
841
  * Returns whether the given value matches the micromatch pattern, converting non-string values to strings.
913
842
  * Optimized version with caching for better performance.
@@ -915,7 +844,7 @@ declare class BaseElementsMatcher {
915
844
  * @param pattern The micromatch pattern to match against.
916
845
  * @returns Whether the value matches the pattern.
917
846
  */
918
- protected isMicromatchMatch(value: unknown, pattern: MicromatchPattern): boolean;
847
+ protected isMicromatchMatch(value: unknown, pattern: MicromatchPatternNullable): boolean;
919
848
  /**
920
849
  * Returns whether the given value matches the micromatch pattern after rendering it as a template.
921
850
  * @param pattern The micromatch pattern to render and match against.
@@ -923,13 +852,13 @@ declare class BaseElementsMatcher {
923
852
  * @param value The value to check.
924
853
  * @returns Whether the value matches the rendered pattern.
925
854
  */
926
- protected isTemplateMicromatchMatch(pattern: MicromatchPattern, templateData: TemplateData, value?: unknown): boolean;
855
+ protected isTemplateMicromatchMatch(pattern: MicromatchPatternNullable, templateData: TemplateData, value?: unknown): boolean;
927
856
  /**
928
857
  * Whether the given element key matches the selector key as booleans.
929
858
  * @param param0 The parameters object.
930
859
  * @returns Whether the element key matches the selector key.
931
860
  */
932
- protected isElementKeyBooleanMatch<T extends BaseElement, S extends BaseElementSelectorData>({
861
+ protected isElementKeyBooleanMatch<T extends BaseElementDescription, S extends BaseElementSelectorData>({
933
862
  /** The element to check. */
934
863
  element,
935
864
  /** The selector to check against. */
@@ -952,17 +881,17 @@ declare class BaseElementsMatcher {
952
881
  * @param param0 The parameters object.
953
882
  * @returns Whether the element key matches the selector key.
954
883
  */
955
- protected isElementKeyMicromatchMatch<T extends SelectableElement, S extends BaseElementSelectorData | DependencyElementSelectorData>({ element, selector, elementKey, selectorKey, selectorValue, templateData, }: {
884
+ protected isElementKeyMicromatchMatch<T extends SelectableElement, S extends BaseElementSelectorData>({ element, selector, elementKey, selectorKey, selectorValue, templateData, }: {
956
885
  /** The element to check. */
957
886
  element: T;
958
887
  /** The selector to check against. */
959
888
  selector: S;
960
889
  /** The key of the element to check. */
961
- elementKey: T extends LocalElementKnown ? keyof LocalElementKnown : T extends CoreDependencyElement ? keyof CoreDependencyElement : T extends ExternalDependencyElement ? keyof ExternalDependencyElement : T extends IgnoredElement ? keyof IgnoredElement : keyof LocalDependencyElementKnown;
890
+ elementKey: keyof T;
962
891
  /** The key of the selector to check against. */
963
- selectorKey: S extends DependencyElementSelectorData ? keyof DependencyElementSelectorData : keyof BaseElementSelectorData;
892
+ selectorKey: keyof BaseElementSelectorData;
964
893
  /** The value of the selector key to check against. */
965
- selectorValue?: MicromatchPattern;
894
+ selectorValue?: MicromatchPatternNullable;
966
895
  /** Data to pass when the selector value is rendered as a template */
967
896
  templateData: TemplateData;
968
897
  }): boolean;
@@ -972,8 +901,6 @@ declare class BaseElementsMatcher {
972
901
  * Matcher class to determine if elements match a given selector.
973
902
  */
974
903
  declare class ElementsMatcher extends BaseElementsMatcher {
975
- /** Whether the cache is enabled or not */
976
- private readonly _cacheIsEnabled;
977
904
  /**
978
905
  * Creates a new ElementsSelectorMatcher.
979
906
  * @param config Configuration options for the matcher.
@@ -1030,29 +957,38 @@ declare class ElementsMatcher extends BaseElementsMatcher {
1030
957
  */
1031
958
  private _isOriginMatch;
1032
959
  /**
1033
- * Whether the given element baseSource matches the selector baseSource
1034
- * @param element The element to check.
1035
- * @param selector The selector to check against.
1036
- * @param templateData The data to use for replace in selector value
1037
- * @returns Whether the element baseSource matches the selector baseSource.
1038
- */
1039
- private _isBaseSourceMatch;
1040
- /**
1041
- * Whether the given element source matches the selector source
1042
- * @param element The element to check.
1043
- * @param selector The selector to check against.
1044
- * @param templateData The data to use for replace in selector value
1045
- * @returns Whether the element source matches the selector source.
960
+ * Checks if a single captured values object matches the element.
961
+ * @param capturedValues The captured values to check.
962
+ * @param capturedSelector The captured values selector object to check against
963
+ * @param templateData The data to use for replace in selector values
964
+ * @returns True if all captured values in the selector match those in the element, false otherwise.
1046
965
  */
1047
- private _isSourceMatch;
966
+ private _checkCapturedValuesObject;
1048
967
  /**
1049
968
  * Determines if the captured values of the element match those in the selector.
969
+ * When the selector is an array, the element matches if it matches any of the array elements (OR logic).
1050
970
  * @param element The element to check.
1051
971
  * @param selector The selector to check against
1052
972
  * @param templateData The data to use for replace in selector values
1053
973
  * @returns True if the captured values match, false otherwise.
1054
974
  */
1055
975
  private _isCapturedValuesMatch;
976
+ /**
977
+ * Determines if the parent captured values match the selector.
978
+ * @param parentSelector The parent selector to match.
979
+ * @param parentCaptured The captured values from first parent.
980
+ * @param templateData The data to use for replace in selector values
981
+ * @returns True if the captured values match, false otherwise.
982
+ */
983
+ private _isParentCapturedValuesMatch;
984
+ /**
985
+ * Whether the given element first parent matches the selector parent.
986
+ * @param element The element to check.
987
+ * @param selector The selector to check against.
988
+ * @param templateData The data to use for replace in selector values
989
+ * @returns Whether the first parent matches the selector parent.
990
+ */
991
+ private _isParentMatch;
1056
992
  /**
1057
993
  * Determines if the isIgnored property of the element matches that in the selector.
1058
994
  * @param element The element to check.
@@ -1080,16 +1016,16 @@ declare class ElementsMatcher extends BaseElementsMatcher {
1080
1016
  * It omits checks in keys applying only to dependency between elements, such as relationship.
1081
1017
  * @param element The element to check.
1082
1018
  * @param selector The selector to check against.
1083
- * @param options Extra options for matching, such as templates data, globals for dependency selectors, etc.
1019
+ * @param options Extra options for matching, such as templates data, etc.
1084
1020
  * @returns The selector matching result for the given element, or null if none matches.
1085
1021
  */
1086
- getSelectorMatching(element: ElementDescription, selector: BaseElementsSelector, { extraTemplateData }?: MatcherOptions): ElementSelectorData | null;
1022
+ getSelectorMatching(element: ElementDescription, selector: BaseElementsSelector, { extraTemplateData }?: MatcherOptions): BaseElementSelectorData | null;
1087
1023
  /**
1088
1024
  * Returns whether the given element matches the selector.
1089
1025
  * It omits checks in keys applying only to dependency between elements, such as relationship.
1090
1026
  * @param element The element to check.
1091
1027
  * @param selector The selector to check against.
1092
- * @param options Extra options for matching, such as templates data, globals for dependency selectors, etc.
1028
+ * @param options Extra options for matching, such as templates data, etc.
1093
1029
  * @returns Whether the element matches the selector properties applying to elements.
1094
1030
  */
1095
1031
  isElementMatch(element: ElementDescription, selector: BaseElementsSelector, options?: MatcherOptions): boolean;
@@ -1117,12 +1053,6 @@ declare class DependenciesMatcher extends BaseElementsMatcher {
1117
1053
  * @returns The normalized dependency selector.
1118
1054
  */
1119
1055
  private _normalizeDependencySelector;
1120
- /**
1121
- * Converts a DependencyElementSelectorData to a BaseElementSelectorData, by removing dependency-specific properties.
1122
- * @param selector The dependency element selector data.
1123
- * @returns The base element selector data.
1124
- */
1125
- private _convertDependencyElementSelectorDataToBaseElementSelectorData;
1126
1056
  /**
1127
1057
  * Returns the selectors matching result for the given dependency.
1128
1058
  * @param dependency The dependency description.
@@ -1130,14 +1060,22 @@ declare class DependenciesMatcher extends BaseElementsMatcher {
1130
1060
  * @param extraTemplateData The extra template data for selector values.
1131
1061
  * @returns The selectors matching result for the given dependency.
1132
1062
  */
1133
- private _getSelectorMatching;
1063
+ private _getSelectorsMatching;
1134
1064
  /**
1135
1065
  * Determines if the dependency relationship matches the selector.
1136
1066
  * @param dependency The dependency description.
1137
1067
  * @param selector The data of an element selector.
1138
1068
  * @returns Whether the dependency relationship matches the selector.
1139
1069
  */
1140
- private _relationshipMatches;
1070
+ private _relationshipFromMatches;
1071
+ /**
1072
+ * Determines if the dependency origin relationship matches the selector.
1073
+ * @param selector The dependency selector data.
1074
+ * @param relationship The relationship from origin element to target element.
1075
+ * @param templateData The template data for rendering selector values.
1076
+ * @returns Whether the dependency origin relationship matches.
1077
+ */
1078
+ private _relationshipToMatches;
1141
1079
  /**
1142
1080
  * Determines if the selector matches an specific kind
1143
1081
  * @param selector The dependency selector data
@@ -1163,34 +1101,42 @@ declare class DependenciesMatcher extends BaseElementsMatcher {
1163
1101
  */
1164
1102
  private _nodeKindMatches;
1165
1103
  /**
1166
- * Determines if the dependency description matches the selector for 'from'.
1104
+ * Determines if the dependency description matches the selector for 'to'.
1167
1105
  * @param dependency The dependency description.
1168
- * @param fromSelector The selector for 'from' elements.
1106
+ * @param toSelector The selector for 'to' elements.
1169
1107
  * @param templateData The template data for rendering selector values
1170
- * @returns Whether the dependency properties match the selector for 'from'.
1108
+ * @returns Whether the dependency properties match the selector for 'to'.
1171
1109
  */
1172
- private _dependencyFromPropertiesMatch;
1110
+ private _sourceMatches;
1173
1111
  /**
1174
- * Determines if the dependency description matches the selector for 'to'.
1112
+ * Determines if the selector matches the module
1113
+ * @param selector The dependency selector data
1114
+ * @param module The module to check
1115
+ * @param templateData The template data for rendering selector values
1116
+ * @returns Whether the selector matches the module
1117
+ */
1118
+ private _moduleMatches;
1119
+ /**
1120
+ * Determines if the dependency description matches the selector for dependency metadata.
1175
1121
  * @param dependency The dependency description.
1176
- * @param toSelector The selector for 'to' elements.
1122
+ * @param selectorData The selector for dependency metadata.
1177
1123
  * @param templateData The template data for rendering selector values
1178
- * @returns Whether the dependency properties match the selector for 'to'.
1124
+ * @returns Whether the dependency properties match the selector.
1179
1125
  */
1180
- private _dependencyToPropertiesMatch;
1126
+ private _dependencyPropertiesMatch;
1181
1127
  /**
1182
1128
  * Returns the selectors matching result for the given dependency.
1183
1129
  * @param dependency The dependency to check.
1184
1130
  * @param selector The selector to check against.
1185
- * @param options Extra options for matching, such as templates data, globals for dependency selectors, etc.
1131
+ * @param options Extra options for matching, such as templates data, etc.
1186
1132
  * @returns The matching result for the dependency against the selector.
1187
1133
  */
1188
- getSelectorsMatching(dependency: DependencyDescription, selector: DependencySelector, { extraTemplateData, dependencySelectorsGlobals, }?: MatcherOptions): DependencyMatchResult;
1134
+ getSelectorsMatching(dependency: DependencyDescription, selector: DependencySelector, { extraTemplateData }?: MatcherOptions): DependencyMatchResult;
1189
1135
  /**
1190
1136
  * Returns whether the given dependency matches the selector.
1191
1137
  * @param dependency The dependency to check.
1192
1138
  * @param selector The selector to check against.
1193
- * @param options Extra options for matching, such as templates data, globals for dependency selectors, etc.
1139
+ * @param options Extra options for matching, such as templates data, etc.
1194
1140
  * @returns Whether the dependency matches the selector properties.
1195
1141
  */
1196
1142
  isDependencyMatch(dependency: DependencyDescription, selector: DependencySelector, options?: MatcherOptions): boolean;
@@ -1213,13 +1159,13 @@ declare function isSimpleElementSelectorByType(value: unknown): value is SimpleE
1213
1159
  * @param value The value to check.
1214
1160
  * @returns True if the selector is a base element selector
1215
1161
  */
1216
- declare function isBaseElementSelectorData(value: unknown): value is ElementSelectorData;
1162
+ declare function isBaseElementSelectorData(value: unknown): value is BaseElementSelectorData;
1217
1163
  /**
1218
1164
  * Determines if the given selector is an element or dependency element selector data.
1219
1165
  * @param value The value to check.
1220
1166
  * @returns True if the selector is an element or dependency element selector data, false otherwise.
1221
1167
  */
1222
- declare function isElementSelectorData(value: unknown): value is ElementSelectorData;
1168
+ declare function isElementSelectorData(value: unknown): value is BaseElementSelectorData;
1223
1169
  /**
1224
1170
  * Determines if the given selector is an element selector with options.
1225
1171
  * @param value The value to check.
@@ -1239,51 +1185,35 @@ declare function isElementSelector(value: unknown): value is ElementSelector;
1239
1185
  */
1240
1186
  declare function isElementsSelector(value: unknown): value is ElementSelectors;
1241
1187
  /**
1242
- * Determines if the given value is a dependency selector.
1243
- * @param value The value to check
1244
- * @returns True if the value is a dependency selector, false otherwise.
1245
- */
1246
- declare function isDependencySelector(value: unknown): value is DependencySelector;
1247
- /**
1248
- * Determines if the given value is external library selector options with a path.
1249
- * @param value The value to check.
1250
- * @returns True if the value is external library selector options with a path, false otherwise.
1188
+ * Normalizes a selector into ElementSelectorData format.
1189
+ * @param selector The selector to normalize.
1190
+ * @returns The normalized selector data.
1251
1191
  */
1252
- declare function isExternalLibrarySelectorOptionsWithPath(value: unknown): value is ExternalLibrarySelectorOptions & {
1253
- path: string | string[];
1254
- };
1192
+ declare function normalizeElementSelector(selector: BaseElementSelector): BaseElementSelectorData;
1255
1193
  /**
1256
- * Determines if the given value is external library selector options with specifiers.
1257
- * @param value The value to check.
1258
- * @returns True if the value is external library selector options with specifiers, false otherwise.
1259
- */
1260
- declare function isExternalLibrarySelectorOptionsWithSpecifiers(value: unknown): value is ExternalLibrarySelectorOptions & {
1261
- specifiers: string[];
1262
- };
1263
- /**
1264
- * Determines if the given value is external library selector options.
1265
- * @param value The value to check.
1266
- * @returns True if the value is external library selector options, false otherwise.
1194
+ * Normalizes an ElementsSelector into an array of ElementSelectorData.
1195
+ * @param elementsSelector The elements selector, in any supported format.
1196
+ * @returns The normalized array of selector data.
1267
1197
  */
1268
- declare function isExternalLibrarySelectorOptions(value: unknown): value is ExternalLibrarySelectorOptions;
1198
+ declare function normalizeElementsSelector(elementsSelector: BaseElementsSelector): BaseElementSelectorData[];
1269
1199
  /**
1270
- * Determines if the given value is an external library selector with options.
1271
- * @param value The value to check.
1272
- * @returns True if the value is an external library selector with options, false otherwise.
1200
+ * Determines if the given value is a dependency selector.
1201
+ * @param value The value to check
1202
+ * @returns True if the value is a dependency selector, false otherwise.
1273
1203
  */
1274
- declare function isExternalLibrarySelectorWithOptions(value: unknown): value is ExternalLibrarySelectorWithOptions;
1204
+ declare function isDependencySelector(value: unknown): value is DependencySelector;
1275
1205
  /**
1276
- * Determines if the given value is an external library selector.
1206
+ * Determines if the given value is dependency metadata selector data.
1277
1207
  * @param value The value to check.
1278
- * @returns True if the value is an external library selector, false otherwise.
1208
+ * @returns True if the value is dependency metadata selector data, false otherwise.
1279
1209
  */
1280
- declare function isExternalLibrarySelector(value: unknown): value is ExternalLibrarySelector;
1210
+ declare function isDependencyDataSelectorData(value: unknown): value is DependencyDataSelectorData;
1281
1211
  /**
1282
- * Determines if the given value is an external libraries selector.
1212
+ * Determines if the given value is dependency metadata selector(s).
1283
1213
  * @param value The value to check.
1284
- * @returns True if the value is an external libraries selector, false otherwise.
1214
+ * @returns True if the value is dependency metadata selector(s), false otherwise.
1285
1215
  */
1286
- declare function isExternalLibrariesSelector(value: unknown): value is ExternalLibrariesSelector;
1216
+ declare function isDependencyDataSelector(value: unknown): value is DependencyDataSelector;
1287
1217
 
1288
1218
  /**
1289
1219
  * Matcher class to evaluate if elements or dependencies match given selectors.
@@ -1301,6 +1231,18 @@ declare class Matcher {
1301
1231
  * @param globalCache Global cache instance.
1302
1232
  */
1303
1233
  constructor(descriptors: ElementDescriptors, elementsMatcher: ElementsMatcher, dependenciesMatcher: DependenciesMatcher, config: DescriptorOptionsNormalized, micromatch: Micromatch);
1234
+ /**
1235
+ * Describes an element given its file path.
1236
+ * @param filePath The path of the file to describe.
1237
+ * @returns The description of the element.
1238
+ */
1239
+ describeElement(filePath: string): ElementDescription;
1240
+ /**
1241
+ * Describes elements in a dependency relationship, and provides additional information about the dependency itself.
1242
+ * @param options The options for describing the elements and the dependency details.
1243
+ * @returns The description of the dependency between the elements.
1244
+ */
1245
+ describeDependency(options: DescribeDependencyOptions): DependencyDescription;
1304
1246
  /**
1305
1247
  * Determines if an element matches a given selector.
1306
1248
  * @param filePath The file path of the element
@@ -1308,7 +1250,7 @@ declare class Matcher {
1308
1250
  * @param options Extra matcher options
1309
1251
  * @returns True if the element matches the selector, false otherwise
1310
1252
  */
1311
- private _isElementMatch;
1253
+ isElementMatch(filePath: string, selector: ElementsSelector, options?: MatcherOptions): boolean;
1312
1254
  /**
1313
1255
  * Determines if a dependency matches a given selector.
1314
1256
  * @param dependencyData The data describing the dependency
@@ -1316,15 +1258,7 @@ declare class Matcher {
1316
1258
  * @param options Extra matcher options
1317
1259
  * @returns True if the dependency matches the selector, false otherwise
1318
1260
  */
1319
- private _isDependencyMatch;
1320
- /**
1321
- * Determines if the given element or dependency matches the provided selector.
1322
- * @param descriptorOptions The file path or dependency options to describe the element or dependency
1323
- * @param selector The selector to match against
1324
- * @param options Extra matcher options
1325
- */
1326
- isMatch(descriptorOptions: string, selector: ElementsSelector, options?: MatcherOptions): boolean;
1327
- isMatch(descriptorOptions: DescribeDependencyOptions, selector: DependencySelector, options?: MatcherOptions): boolean;
1261
+ isDependencyMatch(dependencyData: DescribeDependencyOptions, selector: DependencySelector, options?: MatcherOptions): boolean;
1328
1262
  /**
1329
1263
  * Determines the selector matching for an element.
1330
1264
  * @param filePath The file path of the element
@@ -1332,7 +1266,7 @@ declare class Matcher {
1332
1266
  * @param options Extra options for matching
1333
1267
  * @returns The matching selector data or null if no match is found
1334
1268
  */
1335
- private _getElementSelectorMatching;
1269
+ getElementSelectorMatching(filePath: string, selector: ElementsSelector, options?: MatcherOptions): BaseElementSelectorData | null;
1336
1270
  /**
1337
1271
  * Determines the selector matching for a dependency.
1338
1272
  * @param dependencyData The data describing the dependency
@@ -1340,44 +1274,23 @@ declare class Matcher {
1340
1274
  * @param options Extra options for matching
1341
1275
  * @returns The matching dependency result or null if no match is found
1342
1276
  */
1343
- private _getDependencySelectorMatching;
1344
- /**
1345
- * Determines the selector matching for a dependency or element.
1346
- * @param descriptorOptions The file path or dependency options to describe the element or dependency
1347
- * @param selector The selectors to match against
1348
- * @param options Extra options for matching
1349
- * @returns The matching dependency result or element selector data, or null if no match is found
1350
- */
1351
- getSelectorMatching(descriptorOptions: string, selector: ElementsSelector, options?: MatcherOptions): ElementSelectorData | null;
1352
- getSelectorMatching(descriptorOptions: DescribeDependencyOptions, selector: DependencySelector, options?: MatcherOptions): DependencyMatchResult | null;
1277
+ getDependencySelectorMatching(dependencyData: DescribeDependencyOptions, selector: DependencySelector, options?: MatcherOptions): DependencyMatchResult;
1353
1278
  /**
1354
1279
  * Returns the selectors matching result for the given element or dependency description.
1355
1280
  * @param description The element or dependency description to check.
1356
1281
  * @param selector The selector to check against.
1357
- * @param options Extra options for matching, such as templates data, globals for dependency selectors, etc.
1282
+ * @param options Extra options for matching, such as templates data, etc.
1358
1283
  * @returns The selectors matching result for the given description, and whether it matches or not.
1359
1284
  */
1360
- getSelectorMatchingDescription(description: DependencyDescription, selector: DependencySelector, options?: MatcherOptions): DependencyMatchResult;
1361
- getSelectorMatchingDescription(description: ElementDescription, selector: ElementsSelector, options?: MatcherOptions): ElementSelectorData;
1362
- /**
1363
- * Describes an element given its file path.
1364
- * @param filePath The path of the file to describe.
1365
- * @returns The description of the element.
1366
- */
1367
- describeElement(filePath: string): FileElement;
1368
- /**
1369
- * Describes a dependency element given its dependency source and file path.
1370
- * @param dependencySource The source of the dependency.
1371
- * @param filePath The path of the file being the dependency, if known.
1372
- * @returns The description of the dependency element.
1373
- */
1374
- describeDependencyElement(dependencySource: string, filePath?: string): DependencyElementDescription;
1285
+ getDependencySelectorMatchingDescription(description: DependencyDescription, selector: DependencySelector, options?: MatcherOptions): DependencyMatchResult;
1375
1286
  /**
1376
- * Describes elements in a dependency relationship, and provides additional information about the dependency itself.
1377
- * @param options The options for describing the elements and the dependency details.
1378
- * @returns The description of the dependency between the elements.
1287
+ * Returns the first element selector matching result for the given element description.
1288
+ * @param description The element description to check.
1289
+ * @param selector The selector to check against.
1290
+ * @param options Extra options for matching, such as templates data, etc.
1291
+ * @returns The first matching selector result for the given description, or null if no match is found.
1379
1292
  */
1380
- describeDependency(options: DescribeDependencyOptions): DependencyDescription;
1293
+ getElementSelectorMatchingDescription(description: ElementDescription, selector: ElementsSelector, options?: MatcherOptions): BaseElementSelectorData | null;
1381
1294
  /**
1382
1295
  * Clears all caches.
1383
1296
  */
@@ -1427,14 +1340,7 @@ declare class Descriptors {
1427
1340
  * @param filePath The path of the file to describe.
1428
1341
  * @returns The description of the element.
1429
1342
  */
1430
- describeElement(filePath?: string): FileElement;
1431
- /**
1432
- * Describes a dependency element given its dependency source and file path.
1433
- * @param dependencySource The source of the dependency.
1434
- * @param filePath The path of the file being the dependency, if known.
1435
- * @returns The description of the dependency element.
1436
- */
1437
- describeDependencyElement(dependencySource: string, filePath?: string): DependencyElementDescription;
1343
+ describeElement(filePath?: string): ElementDescription;
1438
1344
  /**
1439
1345
  * Describes elements in a dependency relationship, and provides additional information about the dependency itself.
1440
1346
  * @param options The options for describing the elements and the dependency details.
@@ -1574,7 +1480,7 @@ declare class ElementsDescriptor {
1574
1480
  * @param dependencySource The source of the dependency to check.
1575
1481
  * @returns The base source of the external module. (e.g., for "@scope/package/submodule", it returns "@scope/package")
1576
1482
  */
1577
- private _getExternalOrCoreModuleBaseSource;
1483
+ private _getExternalOrCoreModuleModule;
1578
1484
  /**
1579
1485
  * Determines if a file path is outside the configured root path.
1580
1486
  * @param filePath The file path to check.
@@ -1670,14 +1576,14 @@ declare class ElementsDescriptor {
1670
1576
  * @param filePath The path of the file to describe. Can be absolute if rootPath is configured, or relative if not.
1671
1577
  * @returns The description of the element.
1672
1578
  */
1673
- describeElement(filePath?: string): FileElement;
1579
+ describeElement(filePath?: string): ElementDescription;
1674
1580
  /**
1675
- * Describes a dependency element given its dependency source and file path.
1581
+ * Describes a dependency target element given dependency source and target file path.
1582
+ * @param filePath The path of the dependency target file, if known. Can be absolute if rootPath is configured, or relative if not.
1676
1583
  * @param dependencySource The source of the dependency.
1677
- * @param filePath The path of the file being the dependency, if known. Can be absolute if rootPath is configured, or relative if not.
1678
1584
  * @returns The description of the dependency element.
1679
1585
  */
1680
- describeDependencyElement(dependencySource: string, filePath?: string): DependencyElementDescription;
1586
+ describeElement(filePath: string | undefined, dependencySource: string): ElementDescriptionWithSource;
1681
1587
  }
1682
1588
 
1683
1589
  /**
@@ -1846,4 +1752,4 @@ declare class CacheManager<CacheKey extends NotUndefined, CachedValue> {
1846
1752
  setFromSerialized(serializedCache: Record<string, CachedValue>): void;
1847
1753
  }
1848
1754
 
1849
- 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 };
1755
+ export { type BaseElementDescription, type BaseElementDescriptor, type BaseElementSelector, type BaseElementSelectorData, type BaseElementSelectorWithOptions, type BaseElementsSelector, CacheManager, type CapturedValues, type CapturedValuesSelector, type ConfigOptions, type ConfigOptionsNormalized, type CoreElementDescription, 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 DependencyDataSelector, type DependencyDataSelectorData, type DependencyDescription, type DependencyElementSelectorData, 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 ElementDescriptionWithSource, type ElementDescriptor, type ElementDescriptorMode, type ElementDescriptorPattern, type ElementDescriptorWithCategory, type ElementDescriptorWithType, type ElementDescriptorWithTypeAndCategory, type ElementDescriptors, type ElementOrigin, type ElementParent, type ElementSelector, type ElementSelectorWithOptions, type ElementSelectors, Elements, type ElementsDependencyInfo, ElementsDescriptor, type ElementsDescriptorSerializedCache, ElementsMatcher, type ElementsMatcherSerializedCache, type ElementsSelector, type ElementsSerializedCache, type ExternalElementDescription, type FileElementsSerializedCache, type FlagAsExternalOptions, type FlagAsExternalOptionsNormalized, type IgnoredElement, type LocalElementKnown, type LocalElementUnknown, Matcher, type MatcherOptions, type MatcherSerializedCache, type MatchersOptionsNormalized, type MicromatchPattern, type MicromatchPatternNullable, type MicromatchSerializedCache, type NotUndefined, type ObjectCacheKey, type ParentElementSelectorData, type SelectableElement, type SimpleElementSelectorByType, type TemplateData, isBaseElement, isBaseElementDescriptor, isBaseElementSelectorData, isCapturedValuesSelector, isCoreDependencyElement, isDependencyDataSelector, isDependencyDataSelectorData, isDependencyDescription, isDependencyKind, isDependencyRelationship, isDependencyRelationshipDescription, isDependencySelector, isElementDescription, isElementDescriptor, isElementDescriptorMode, isElementDescriptorPattern, isElementDescriptorWithCategory, isElementDescriptorWithType, isElementSelector, isElementSelectorData, isElementSelectorWithLegacyOptions, isElementsDependencyInfo, isElementsSelector, isExternalDependencyElement, isIgnoredElement, isInternalDependency, isKnownLocalElement, isLocalDependencyElement, isLocalElement, isSimpleElementSelectorByType, isUnknownLocalElement, normalizeElementSelector, normalizeElementsSelector };