Skip to content

Add architecture.md #105

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 17, 2022
Merged

Add architecture.md #105

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions docs/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
Architecture overview
=====================

![Architecture of the extension](images/architecture.svg)

Overview
--------

* Each module is handled separately, but along the same lines
* Frontend-backend separation
* Singleton instances, which are returned for testing
* An outer static wrapper, which creates singleton instances
* These instances have more readable syntax thanks to `this`
* Registers commands, callbacks, handler instances through the VSCode API

Frontend
--------

Presents the extension's data inside VSCode.

* Editor
* Anything concerning VSCode's text editor, although it's a tiny bit big now
* Main parts are diagnostics (which handles the underlines) and CodeLens (which handles the repr. step descriptions)
* Executor, showing the state of CodeChecker on the statusbar
* Initializer, for initially running CodeChecker log
* Logger, for all output logs, even from the backend
* Navigation, handling keyboard navigation and any kind of movement
* Sidebar
* Is the main way to interact with the extension
* Overview: flat list, displays basic stats and provides quick buttons for analyzing etc.
* Reports: nested list, displays found bugs and reproduction steps
* There's 2 things we cannot do in the editor:
* Show/hide reproduction steps, and navigation to each repr. step
* Those require the sidebar tab to be used

Backend
-------

Receives commands and calls from VSCode, sends events to the frontend.

* Parser and types
* Parsing was an important step when .plist was in place, now not so much
* Only purpose now is parsing the metadata.json
* Types are 1:1 with CodeChecker's outputs
* Processor
* Makes parsed results available to the frontend
* Also has events when files are changed, etc.
* Monitors metadata.json and workspace changes, reloads when updated
* Executor
* Any kind of CodeChecker running goes through this
* Can be called via commands, build commands, or directly
* `process.ts` handles the actual instance scheduling, while `bridge.ts` prepares the command lines, comp.db. path, etc.

Main data processing workflow:

* Processor detects a file update event, tab change event, or a re-analyze build task is called
* Executor bridge adds a process, and the manager schedules and runs it
* All logs are forwarded to the frontend
* Result is either an OK, or gets passed over to the parser (from the parse command)
* Parser transforms it into the internal types, which are then loaded into the processor
* Processor fires events that data is updated, which is then read by the frontend
130 changes: 130 additions & 0 deletions docs/images/architecture.drawio
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
<mxfile host="65bd71144e">
<diagram id="xBclP24ozev2WuGMtXyt" name="Architecture">
<mxGraphModel dx="912" dy="880" grid="1" gridSize="10" guides="0" tooltips="1" connect="1" arrows="1" fold="1" page="0" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
<mxCell id="28" value="Response" style="edgeStyle=none;rounded=0;html=1;exitX=0.213;exitY=1;exitDx=0;exitDy=0;entryX=0.213;entryY=-0.006;entryDx=0;entryDy=0;entryPerimeter=0;exitPerimeter=0;dashed=1;" parent="1" source="2" target="7" edge="1">
<mxGeometry x="0.2642" relative="1" as="geometry">
<mxPoint as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="29" value="Data Update&lt;br&gt;Events" style="edgeStyle=none;rounded=0;html=1;exitX=0.321;exitY=1;exitDx=0;exitDy=0;entryX=0.321;entryY=0.007;entryDx=0;entryDy=0;exitPerimeter=0;entryPerimeter=0;" parent="1" source="2" target="7" edge="1">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="38" value="Log&lt;br&gt;Events" style="edgeStyle=none;rounded=0;html=1;exitX=0.421;exitY=1;exitDx=0;exitDy=0;entryX=0.422;entryY=0.007;entryDx=0;entryDy=0;entryPerimeter=0;startArrow=none;startFill=0;exitPerimeter=0;" parent="1" source="2" target="7" edge="1">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="2" value="&lt;div&gt;&lt;span&gt;Backend&lt;/span&gt;&lt;/div&gt;&lt;br&gt;Only responds to external events!&lt;br&gt;Does not call frontend, only via vscode commands and events&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;div&gt;&lt;br&gt;&lt;/div&gt;&lt;div&gt;&lt;br&gt;&lt;/div&gt;&lt;div&gt;&lt;br&gt;&lt;/div&gt;" style="rounded=1;whiteSpace=wrap;html=1;align=center;strokeWidth=3;strokeColor=#99FFFF;" parent="1" vertex="1">
<mxGeometry x="80" y="100" width="610" height="170" as="geometry"/>
</mxCell>
<mxCell id="13" value="CC parse" style="edgeStyle=none;html=1;exitX=1;exitY=0.75;exitDx=0;exitDy=0;entryX=0;entryY=0.75;entryDx=0;entryDy=0;dashed=1;" parent="1" source="3" target="4" edge="1">
<mxGeometry x="-0.1129" y="-7" relative="1" as="geometry">
<mxPoint as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="34" value="parse, analyze, version" style="edgeStyle=none;rounded=0;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;startArrow=classic;startFill=1;" parent="1" source="3" target="33" edge="1">
<mxGeometry x="0.5" relative="1" as="geometry">
<mxPoint as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="3" value="Executor&lt;br&gt;&lt;br&gt;Handles running&lt;br&gt;CodeChecker" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#6d8764;fontColor=#ffffff;strokeColor=#3A5431;" parent="1" vertex="1">
<mxGeometry x="120" y="170" width="130" height="70" as="geometry"/>
</mxCell>
<mxCell id="14" value="&amp;nbsp; ParseResult" style="edgeStyle=none;html=1;exitX=1;exitY=0.75;exitDx=0;exitDy=0;entryX=0;entryY=0.75;entryDx=0;entryDy=0;dashed=1;" parent="1" source="4" target="5" edge="1">
<mxGeometry x="-0.1871" y="-7" relative="1" as="geometry">
<mxPoint as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="16" style="edgeStyle=none;html=1;exitX=1;exitY=0.25;exitDx=0;exitDy=0;entryX=0;entryY=0.25;entryDx=0;entryDy=0;dashed=1;" parent="1" source="4" target="5" edge="1">
<mxGeometry relative="1" as="geometry">
<mxPoint x="530" y="189" as="targetPoint"/>
</mxGeometry>
</mxCell>
<mxCell id="17" value="&amp;nbsp; &amp;nbsp;MetadataFile" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" parent="16" vertex="1" connectable="0">
<mxGeometry x="0.3009" relative="1" as="geometry">
<mxPoint x="-16" y="-8" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="4" value="Parser&lt;br&gt;&lt;br&gt;Parse data from CC&lt;br&gt;into internal repr." style="rounded=1;whiteSpace=wrap;html=1;fillColor=#647687;fontColor=#ffffff;strokeColor=#314354;" parent="1" vertex="1">
<mxGeometry x="317.5" y="170" width="135" height="70" as="geometry"/>
</mxCell>
<mxCell id="20" style="edgeStyle=orthogonalEdgeStyle;html=1;exitX=0.25;exitY=1;exitDx=0;exitDy=0;entryX=0.75;entryY=1;entryDx=0;entryDy=0;rounded=0;" parent="1" source="5" target="3" edge="1">
<mxGeometry relative="1" as="geometry">
<Array as="points">
<mxPoint x="558" y="250"/>
<mxPoint x="218" y="250"/>
</Array>
</mxGeometry>
</mxCell>
<mxCell id="21" value="Files modified on disk, Reload commands, etc." style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" parent="20" vertex="1" connectable="0">
<mxGeometry x="-0.1808" y="-1" relative="1" as="geometry">
<mxPoint x="-35" y="11" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="5" value="Processor&lt;br&gt;&lt;br&gt;Core of the API&lt;br&gt;Updates, commands.." style="rounded=1;whiteSpace=wrap;html=1;fillColor=#a0522d;fontColor=#ffffff;strokeColor=#6D1F00;" parent="1" vertex="1">
<mxGeometry x="520" y="170" width="150" height="70" as="geometry"/>
</mxCell>
<mxCell id="11" value="ExtensionAPI&lt;br&gt;calls" style="edgeStyle=none;html=1;exitX=0.15;exitY=-0.006;exitDx=0;exitDy=0;exitPerimeter=0;entryX=0.15;entryY=1;entryDx=0;entryDy=0;entryPerimeter=0;" parent="1" source="7" target="2" edge="1">
<mxGeometry x="0.25" relative="1" as="geometry">
<mxPoint x="164" y="270" as="targetPoint"/>
<mxPoint as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="30" value="UI update events" style="edgeStyle=none;rounded=0;html=1;exitX=0.564;exitY=0;exitDx=0;exitDy=0;entryX=0.194;entryY=1.052;entryDx=0;entryDy=0;entryPerimeter=0;exitPerimeter=0;" parent="1" source="7" target="22" edge="1">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="7" value="&lt;div&gt;Frontend&lt;/div&gt;&lt;br&gt;Handles all user-facing interactions, wrapper for most backend stuff&lt;br&gt;Calls the backend via the exposed API, and vscode commands&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;div&gt;&lt;br&gt;&lt;/div&gt;&lt;div&gt;&lt;br&gt;&lt;/div&gt;" style="rounded=1;whiteSpace=wrap;html=1;align=center;strokeWidth=3;strokeColor=#FFB366;" parent="1" vertex="1">
<mxGeometry x="80" y="350" width="610" height="150" as="geometry"/>
</mxCell>
<mxCell id="8" value="Editor&lt;br&gt;&lt;br&gt;Everything in Code's text editor&lt;br&gt;Underline, CodeLens, Commands..." style="rounded=1;whiteSpace=wrap;html=1;fillColor=#76608a;fontColor=#ffffff;strokeColor=#432D57;" parent="1" vertex="1">
<mxGeometry x="120" y="420" width="200" height="70" as="geometry"/>
</mxCell>
<mxCell id="43" value="Navigation" style="edgeStyle=none;rounded=0;html=1;exitX=0;exitY=0.75;exitDx=0;exitDy=0;entryX=1;entryY=0.75;entryDx=0;entryDy=0;startArrow=none;startFill=0;" parent="1" source="9" target="8" edge="1">
<mxGeometry x="0.0769" y="8" relative="1" as="geometry">
<mxPoint as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="44" value="&amp;nbsp; &amp;nbsp;Show repr. steps" style="edgeStyle=none;rounded=0;html=1;exitX=0;exitY=0.25;exitDx=0;exitDy=0;entryX=1;entryY=0.25;entryDx=0;entryDy=0;startArrow=none;startFill=0;" parent="1" source="9" target="8" edge="1">
<mxGeometry x="0.0769" y="-7" relative="1" as="geometry">
<mxPoint as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="9" value="Sidebar&lt;br&gt;&lt;br&gt;Main way to interact with the extension&lt;br&gt;Stats, Details, Buttons for every action" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#647687;fontColor=#ffffff;strokeColor=#314354;" parent="1" vertex="1">
<mxGeometry x="450" y="420" width="220" height="70" as="geometry"/>
</mxCell>
<mxCell id="25" value="Commands" style="edgeStyle=none;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.73;entryY=0;entryDx=0;entryDy=0;entryPerimeter=0;" parent="1" source="22" target="7" edge="1">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="27" value="Commands" style="edgeStyle=none;rounded=0;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0.73;entryY=1.012;entryDx=0;entryDy=0;entryPerimeter=0;" parent="1" source="22" target="2" edge="1">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="31" value="Button/click events" style="edgeStyle=none;rounded=0;html=1;exitX=0.788;exitY=1;exitDx=0;exitDy=0;exitPerimeter=0;" parent="1" source="22" edge="1">
<mxGeometry relative="1" as="geometry">
<mxPoint x="620" y="348" as="targetPoint"/>
</mxGeometry>
</mxCell>
<mxCell id="32" value="Settings" style="edgeStyle=none;rounded=0;html=1;exitX=0.188;exitY=-0.098;exitDx=0;exitDy=0;entryX=0.561;entryY=1.006;entryDx=0;entryDy=0;entryPerimeter=0;exitPerimeter=0;startArrow=classic;startFill=1;" parent="1" source="22" target="2" edge="1">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="37" value="Tab change events" style="edgeStyle=none;rounded=0;html=1;exitX=0.791;exitY=0;exitDx=0;exitDy=0;entryX=0.887;entryY=1;entryDx=0;entryDy=0;entryPerimeter=0;startArrow=none;startFill=0;exitPerimeter=0;" parent="1" source="22" target="2" edge="1">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="22" value="VSCode" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#0050ef;fontColor=#ffffff;strokeColor=#001DBC;" parent="1" vertex="1">
<mxGeometry x="360" y="300" width="330" height="20" as="geometry"/>
</mxCell>
<mxCell id="33" value="CodeChecker" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#0050ef;fontColor=#ffffff;strokeColor=#001DBC;" parent="1" vertex="1">
<mxGeometry x="120" y="30" width="130" height="20" as="geometry"/>
</mxCell>
<mxCell id="36" value="Monitor for changes" style="edgeStyle=none;rounded=0;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;startArrow=classic;startFill=1;" parent="1" source="35" target="5" edge="1">
<mxGeometry x="-0.5" relative="1" as="geometry">
<mxPoint as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="35" value="metadata.json" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#0050ef;fontColor=#ffffff;strokeColor=#001DBC;" parent="1" vertex="1">
<mxGeometry x="535" y="30" width="120" height="20" as="geometry"/>
</mxCell>
</root>
</mxGraphModel>
</diagram>
</mxfile>
Loading