Skip to content

Commit 00f301f

Browse files
SebastianWendorfSebastianWendorf
committed
Added initial developer documentation
1 parent 3726e9d commit 00f301f

File tree

9 files changed

+137
-2
lines changed

9 files changed

+137
-2
lines changed

‎docs/content/.obsidian/app.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
{
22
"showInlineTitle": false,
33
"promptDelete": false,
4-
"newFileLocation": "current"
4+
"newFileLocation": "current",
5+
"alwaysUpdateLinks": true
56
}

‎docs/content/development/Codebase Layout.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
aliases:
3+
- codebase layout
4+
---
5+
# Codebase Layout
6+
The codebase of the plugin is structured the following way:
7+
- `docs/`: contains the documentation you're reading right now
8+
- `java/`: contains the Java-based [jQA-Plugin](https://jqassistant-plugin.github.io/jqassistant-lce-docs/architecture/jQAssistant-Plugin)
9+
- `src/main/`: implementation of the [jQA-Plugin](https://jqassistant-plugin.github.io/jqassistant-lce-docs/architecture/jQAssistant-Plugin)
10+
- `o.j.p.t.api`: `TypeScriptScope` and all `Descriptor` interfaces
11+
- `o.j.p.t.impl`
12+
- `filesystem`: custom Implementation of the file resolver
13+
- `mapper`: MapStruct-based mappers and resolvers for POJO-to-Descriptor Mappings (*contains main logic of the plugin*)
14+
- `model`: POJOs that model the JSON output of the [LCE tool](https://jqassistant-plugin.github.io/jqassistant-lce-docs/architecture/LCE-Tool)
15+
- `src/test/`: integration tests for the [jQA-Plugin](https://jqassistant-plugin.github.io/jqassistant-lce-docs/architecture/jQAssistant-Plugin)
16+
- `typescript/`: contains the implementation and tests for the TypeScript [LCE tool](https://jqassistant-plugin.github.io/jqassistant-lce-docs/architecture/LCE-Tool)
17+
- `src/`: implementation of the [LCE tool](https://jqassistant-plugin.github.io/jqassistant-lce-docs/architecture/LCE-Tool)
18+
- `core/`: code for the [LCE framework](https://jqassistant-plugin.github.io/jqassistant-lce-docs/) and all core language features
19+
- `concepts/`: [[Concepts|concept]] implementations
20+
- `post-processors/`: [[Post-Processors|post-processor]] implementations
21+
- `processors/`: [[Processors|processor]] implementations
22+
- `traversers/`: [[Traversers|traverser]] implementations
23+
- `utils/`: various [[Utilities|utility]] functions, etc.
24+
- *the `.ts` files directly contained in this directory model the [LCE framework](https://jqassistant-plugin.github.io/jqassistant-lce-docs/)*
25+
- `react/`: code for the [[React Extension]]
26+
- ... *directories for future extensions*
27+
- `main.ts`: contains entry point of the tool that parses the CLI arguments and initializes the extensions
28+
- `test/`: tests for the [LCE tool](https://jqassistant-plugin.github.io/jqassistant-lce-docs/architecture/LCE-Tool)

‎docs/content/development/Concepts.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
aliases:
3+
- concept
4+
---
5+
# Concepts
6+
-> classes representing [LCE language concepts](https://jqassistant-plugin.github.io/jqassistant-lce-docs/architecture/Language-Concept)
7+
- located in `typescript/src/core/concepts`
8+
- all files end with `.concept.ts`
9+
- may export one or more concept classes each
10+
11+
**Notes for creating new concept classes:**
12+
- each concept class must (indirectly) inherit from `LCEConcept`/`LCENamedConcept`
13+
- each concept class must override the static `conceptId` field with a unique string identifier
14+
- use `CodeCoordinates` class as field type to encode code coordinates
15+
- all type and value concepts are located in `type.concept.ts` and `value.concept.ts` respectively
16+
17+
**`ConceptMap`:**
18+
- [Concept Maps](https://jqassistant-plugin.github.io/jqassistant-lce-docs/architecture/Concept-Map) are realized in their more complex form, integrating parent property names into their index structure
19+
- use `mergeConceptMaps`, `unifyConceptMap`, `singleEntryConceptMap`, `createConceptMap`, and `getAndCastConcepts` utility functions for concise usage of `ConceptMap` instances

‎docs/content/development/Extensions.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
aliases:
3+
- extension
4+
---
5+
# Extensions
6+
-> besides the core language structures, [Extensions](https://jqassistant-plugin.github.io/jqassistant-lce-docs/architecture/Extensions) can be used to implement optional, technology-specific scanning/processing components (i.e. [[Concepts|concepts]], [[Traversers|traversers]], [[Processors|processors]], or [[Post-Processors|post-processors]] and the concept representations in the jQA Plugin)
7+
8+
**LCE:**
9+
- components for each extension is placed in a separate sub-directory in under `typescript/src` (e.g. `typescript/src/react`)
10+
- each extension contains a main module called `extension-name-extractor.ts` that exports a function that adds all processing components of the extension to the [feature collections](https://jqassistant-plugin.github.io/jqassistant-lce-docs/architecture/Feature-Collections) in `typescript/src/core/features.ts`
11+
- `typescript/src/main.ts` must be extended to allow the extension to be activated and initialized
12+
- all processing components are defined in the same manner and directory structure as their core counterparts
13+
14+
**jQA Plugin:**
15+
- each of the technical packages contains sub-packages for the core and each individual extension
16+
- the `ConceptCollection` class has to accommodate all possible concept types that can be emitted by the LCE tool

‎docs/content/development/Post-Processors.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
aliases:
3+
- post-processor
4+
---
5+
# Post-Processors
6+
-> classes representing [LCE post-processors](https://jqassistant-plugin.github.io/jqassistant-lce-docs/architecture/Post-Processors)
7+
- located in `typescript/src/core/post-processors`
8+
- all files end with `.post-processor.ts`
9+
- may export one or more concept classes each
10+
11+
**Notes for creating new post-processor classes:**
12+
- each post-processor class must inherit from `PostProcessor` and implement the `postProcess` method
13+
- all post-processors need to be registered in the `POST_PROCESSORS` [feature collection](https://jqassistant-plugin.github.io/jqassistant-lce-docs/architecture/Feature-Collections) in `features.ts`
14+
- before implementing a new post-processor check if there already exists one that could be modified to also solve the problem at hand

‎docs/content/development/Processors.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
aliases:
3+
- processor
4+
---
5+
# Processors
6+
-> classes representing [LCE Processors](https://jqassistant-plugin.github.io/jqassistant-lce-docs/architecture/Processors)
7+
- located in `typescript/src/core/processors`
8+
- all files end with `.processor.ts`
9+
- may export one or more processor classes each
10+
11+
**Notes for creating new processors:**
12+
- each processor class must inherit from `Processor`
13+
- only the `executionCondition` has to be specified
14+
- `preChildrenProcessing` and `postChildrenProcessing` methods have empty default implementations and can be overridden as needed
15+
- use `CodeCoordinateUtils` to retrieve code coordinates from an ESLint node
16+
- use functions of `processor.utils.ts` for easier handling of the used data structures
17+
- use utility functions from`type.utils.ts` to process type information

‎docs/content/development/Traversers.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
aliases:
3+
- traverser
4+
---
5+
# Traversers
6+
-> [LCE traversers](https://jqassistant-plugin.github.io/jqassistant-lce-docs/architecture/Traversers) are implemented as a modified visitor pattern
7+
- The abstract `Traverser` base class provides the implementation that orchestrates the execution of the other components
8+
- only the `traverseChildren` method that delegates the traversal of potential child nodes to other traversers is abstract and has to be implemented by sub types
9+
- for each AST node type (provided via `@typescript-eslint/utils`) that should be processed a separate `Traverser` implementation has to be provided
10+
- all traverser implementations are located under `typescript/src/core/traversers`
11+
- all files end with `.traverser.ts`
12+
- may export one or more traverser classes each
13+
14+
**Notes for creating new traversers:**
15+
- each traverser class must inherit from `Traverser`
16+
- all traversers need to be registered in the `TRAVERSERS` [feature collection](https://jqassistant-plugin.github.io/jqassistant-lce-docs/architecture/Feature-Collections) in `features.ts`
17+
- before implementing a new traverser check if there already exists one in the collection
18+
- existing traversers may not trigger the traversal for all their child nodes: expand where needed
19+
- use `runTraverserForNode`(`s`) utility function to easily delegate the traversal process
20+
- parent property names should be declared as `public static readonly` members of the implementing class

‎docs/content/development/Utilities.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Utilities
2+
-> there exist various utility modules in the TypeScript LCE to aid development
3+
4+
**Overview:**
5+
- `FileUtils`: operations with files, directories and their paths
6+
- mainly used for normalizing file system paths to consistently use forward slashes (`normalizePath`)
7+
- `ModulePathUtils`: operations on FQNs and the module paths contained within them
8+
- `NodeUtils`: operations to call on Node-specific APIs for package name resolution, etc.
9+
- `processor.utils.ts`: provides various functions to be used by [[Processors|processors]] for easy access to the various processed data structures
10+
- `traverser.utils.ts`: provides functions to be used by [[Traversers|traversers]] to better orchestrate the traversal process
11+
- `ProjectUtils`: contains logic for project detection and information extraction

‎docs/content/index.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,4 +43,13 @@ The tool currently only supports projects using ECMAScript modules.
4343
- triple-slash directives
4444

4545
## Development
46-
This plugin is based on the [LCE Architecture](https://jqassistant-plugin.github.io/jqassistant-lce-docs/).
46+
This plugin is based on the [LCE Architecture](https://jqassistant-plugin.github.io/jqassistant-lce-docs/).
47+
- [[Codebase Layout]]
48+
- [[Extensions]]
49+
50+
**LCE:**
51+
- [[Concepts]]
52+
- [[Traversers]]
53+
- [[Processors]]
54+
- [[Post-Processors]]
55+
- [[Utilities]]

0 commit comments

Comments
 (0)