Added dependency extraction strategy documentation

Author: SebastianWendorf

…opment/Extraction Strategy - Overview.md docs/development/Extraction Strategies.mddocs/development/Extraction Strategy - Overview.md renamed to docs/development/Extraction Strategies.md docs/development/Extraction Strategy - Overview.md renamed to docs/development/Extraction Strategies.md

@@ -1,10 +1,28 @@
-# Extraction Strategy: Overview
+# Extraction Strategies
 -> the extraction of language concepts is achieved by an implementation of the [LCE Architecture](https://jqassistant-plugin.github.io/jqassistant-lce-docs/)
 
+**Information Sources:**
 - the main source of information for extracting concepts from TS source code is the ESLint AST (provided through `@typescript-eslint/typescript-estree`)
 	- use [ESLint Playground](https://typescript-eslint.io/play/) to easily explore the data structures
-- all concepts have to be extracted within a single traversal of the ESLint AST
-	- separate/additional sub-tree traversals are not allowed
 - additional information, mostly related to types, is extracted via the native TypeScript Compiler API (for more information see [here](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) and [here](https://github.com/microsoft/TypeScript-Compiler-Notes/blob/main/README.md)), especially the TypeChecker
 	- direct translation between nodes of the two different ASTs can easily be done via the `services` global context
-	- the Compiler API should be used sparingly, as it is less developer-friendly than the ESLint API
+	- the Compiler API should be used sparingly, as it is less developer-friendly than the ESLint API
+
+**General Guidelines:**
+- all concepts have to be extracted within a single traversal of the ESLint AST
+	- separate/additional sub-tree traversals are not allowed
+
+**Currently Implemented Extraction Strategies:**
+- [[Extraction Strategy - Dependencies|Dependencies and FQNs]]
+- Types
+- Values
+- Imports
+- Exports
+- Classes and Interfaces
+- Function Declarations
+- Variable Declarations
+- Type Aliases
+- Enums
+- Decorators
+- Code Coordinates
+- Special Case: Indexed Access Types

docs/development/Extraction Strategy - Dependencies.md

@@ -0,0 +1,22 @@
+# Extraction Strategy: Dependencies and FQNs
+**Goal:** Creation of [[Node Relation - Dependencies|DEPENDS_ON]] relations between the various concept nodes
+
+**Strategy:**
+1. LCE: While traversing the AST register all referenced identifiers as dependencies (with source and target [[Node Properties - Fully Qualified Names|FQN]]) in a central data structure
+2. LCE: After finishing the traversal aggregate all detected dependencies and store them as [[Concepts|concepts]]
+	- Note: as [[Node Properties - Fully Qualified Names|FQNs]] can't always be resolved fully during the traversal, a resolution of them has to precede the dependency aggregation 
+3. jQA Plugin: Create dependencies using the stored [[Node Properties - Fully Qualified Names|global FQNs]]
+4. jQA Plugin: Fill in all transitive dependencies via Cypher queries
+
+**Central Components:**
+- `LCEDependency`: concept that represents a direct dependency observed in the code
+	- for transitive dependencies see `DependencyResolver`
+- `DependencyResolutionProcessor`: processor that resolves [[Node Properties - Fully Qualified Names|FQN]] references and collects registered dependencies within the AST
+	- executed on the root node of the AST of each source file
+	- registers [[Local Contexts]] that serve as indexes for registering declarations and dependencies within the module as well as schedule [[Node Properties - Fully Qualified Names|FQN]] resolutions at the end of the AST traversal
+	- provides static utility methods for the construction of [[Node Properties - Fully Qualified Names|FQNs]] and the interaction with the [[Local Contexts]] from above
+- `IdentifierDependencyProcessor`: processor that registers dependencies for all referenced identifiers within the code that are not part of one of the other processed declaration constructs
+	- `MemberExpressionDependencyProcessor` handles dependency registration specifically for member expressions (e.g. `myObj.b`)
+-  `ScopeProcessor`/`DeclarationScopeProcessor`: processors that register (un)named [[Node Properties - Fully Qualified Names|FQN]] scopes at all relevant points of the AST traversal to aid [[Node Properties - Fully Qualified Names|FQN]] construction
+- `DependencyResolver` (Java): creates [[Node Relation - Dependencies|DEPENDS_ON]] relations for the extracted direct dependencies and fills in all transitive dependencies via Cypher queries
+	- in a final step all [[Node Relation - Dependencies|DEPENDS_ON]] relations are aggregated

docs/index.md

@@ -46,6 +46,7 @@ The tool currently only supports projects using ECMAScript modules.
 This plugin is based on the [LCE Architecture](https://jqassistant-plugin.github.io/jqassistant-lce-docs/).
 - [[Codebase Layout]]
 - [[Extensions]]
+- *TODO: Testing Strategy*
 
 **Base LCE Architecture Implementation:**
 - [[Concepts]]
@@ -56,4 +57,5 @@ This plugin is based on the [LCE Architecture](https://jqassistant-plugin.github
 - [[Utilities]]
 
 **Extraction Strategies:**
-- *[[Extraction Strategy - Overview|Overview]]*
+- *[[Extraction Strategies|Overview]]*
+- [[Extraction Strategy - Dependencies|Dependencies and FQNs]]

docs/usage/Node Properties - Fully Qualified Names.md

@@ -2,6 +2,7 @@
 aliases:
   - local FQN
   - global FQN
+  - FQN
 ---
 # Fully Qualified Names (FQNs)
 -> node properties that uniquely identify a concept within or across projects

typescript/src/core/processors/dependency-resolution.processor.ts

@@ -23,6 +23,12 @@ export type DeclarationIndex = Map<string, Map<string, FQN>>;
  */
 export type FQNResolverContext = Array<[string[], string, LCENamedConcept]>;
 
+/**
+ * Stores the identifiers for the declaration that encompasses the currently traversed part of the AST.
+ * Multiple of these scopes can be set as Local Contexts on different levels to express nested scopes (e.g a method within a class).
+ *
+ * see `DependencyResolutionProcessor` for more detail.
+ */
 export interface FQNScope {
     globalIdentifier: string;
     localIdentifier: string;

typescript/src/core/processors/instructional-code.processor.ts

@@ -8,7 +8,11 @@ import { ExecutionCondition } from "../execution-condition";
 import { Processor } from "../processor";
 import { getParentPropName } from "../utils/processor.utils";
 import { ClassTraverser } from "../traversers/class.traverser";
-import { ArrowFunctionExpressionTraverser, MemberExpressionTraverser, TaggedTemplateExpressionTraverser } from "../traversers/expression.traverser";
+import {
+    ArrowFunctionExpressionTraverser,
+    MemberExpressionTraverser,
+    TaggedTemplateExpressionTraverser
+} from "../traversers/expression.traverser";
 import { FunctionTraverser } from "../traversers/function.traverser";
 import { MethodTraverser } from "../traversers/method.traverser";
 import { PropertyTraverser } from "../traversers/property.traverser";
@@ -18,6 +22,9 @@ import { TypeAliasDeclarationTraverser } from "../traversers/type-alias-declarat
 import { CoreContextKeys } from "../context.keys";
 import { TraverserContext } from "../traverser";
 
+/**
+ * Registers unnamed `FQNScope` local contexts for all nodes that create a new anonymous scope.
+ */
 export class ScopeProcessor extends Processor {
     public executionCondition: ExecutionCondition = new ExecutionCondition(
         [AST_NODE_TYPES.BlockStatement, AST_NODE_TYPES.ForStatement, AST_NODE_TYPES.ForInStatement, AST_NODE_TYPES.ForOfStatement],
@@ -29,6 +36,9 @@ export class ScopeProcessor extends Processor {
     }
 }
 
+/**
+ * Registers named `FQNScope` local contexts for all declaration nodes.
+ */
 export class DeclarationScopeProcessor extends Processor {
     public executionCondition: ExecutionCondition = new ExecutionCondition(
         [