Published using Google Docs
Softagram Audit for BotFramework-Emulator
Updated automatically every 5 minutes

        

Softagram_logo-black_small.png     case BotFramework-Emulator                    @SoftagramLtd

SOFTAGRAM AUDIT: BotFramework-Emulator

https://github.com/microsoft/BotFramework-Emulator

SUMMARY AND RECOMMENDATIONS

Recommendations

ARCHITECTURE

Internal Architecture

High level

app src  high-level structure

app src main server  high-level structure

Client src design

Critical Code Files, Top 15

Burning Components based on Github Bug Labeled Issues

Most complex code files, Top 15

Maintainability

Architectural limitations for further development

VULNERABILITIES

INTELLECTUAL PROPERTY AND OPEN SOURCE LICENSES

Appendice

Remarks

SUMMARY AND RECOMMENDATIONS

Category

Summary

Notes

General

Code size:

70 kLOC

Mostly TypeScript code, most of it concentrated in packages/app

Total developers:

18 (during one year)

Active developers differ greatly (4 developers in recent 3 months compared to 18 developers in one year). Typical for an open source project.

Active developers:

1-4 (1 month, 3 months)

Number of active distinct developers during the last 3 months, based on version history.

Maintainability

Bug fix ratio %:

22 % during last  year

Fix ratio is at a good level. GitHub integrated issue extractor was used to classify issue ids as either bugs or features based on the project specific convention (label Bug)..

63 technical debt markers

=> low 1 per 1KLOC

Codebase contains very little  amount of technical debt markers such as TODO/FIXME comments. Conversation is one area that seems to have unfinished spec work..

Open source component risks

Vulnerabilities:  

1 acute, several resolved in previous versions

Dependencies are mostly up-to-date. As an exception, electron is in version 4.1.1 that suffers from CVE-2020-15096

Licenses: No incompatible or risky licenses used.

Several code files that have licenses embedded (MIT), and large set of NodeJS packages with various permissive licenses

Architectural quality

Amount of complexity

Business domain complexity is high, somewhat difficult to understand and maintain without the risk of breaking something. Causes long time-to-market for features and bug fixes.

Cohesion and coupling

The system is well engineered in terms of coupling and cohesion. Only a couple of central topics cause drawbacks here.

Amount of dependencies and the health of them

There is quite a large bunch (~100) of directly used external dependencies, but those are sufficiently maintained.

Responsibilities

The responsibilities of the components are well designed.

Fragile sections

There are certain fragile sections (buggy and continuously changing), that may cause problems in the future.

Code readability

Code formatting problems

Code maintainability and readability is fine.

Code duplication

Only some config files (3)  contain copy paste fragments. There are no significant copy paste in the real code files.


Recommendations

Category

Issue

Recommended action

Maintainability

Bug fix ratio: % not calculated

Keep the ratio low :-)

Technical debt markers

- Analyze markers in the most critical components, in priority order (see attr_tech_debt_propagated.csv)

- Decide which TODOs are worth doing and sort them out

- Do not attempt to fix everything, it probably won't pay back.

- Follow the technical debt ratio in Softagram KPI Dashboard 

Open source component risks

Vulnerabilities:

not relevant here

Upgrade electron to newer version.

Licenses: no risky licenses

Monitor usage of open source licenses, to avoid incompatible licenses.

Architectural quality

High complexity, lots of interdependencies and duplication

- Consider the role of Store that now has wide impact..

- See notes on Top 6 critical code files.

- Consider moving few code files into more logical places to make the directory structure more logical (e.g. ui <--> components relationship issue described later)

Code readability

Code formatting problems, naming

Keep code well structured, no urgent actions.

Code duplication

Copy paste detectors not available for TypeScript..


ARCHITECTURE

Internal Architecture

High level

The system consists of app, sdk, extensions and tools. The heatmap shows the LOC metric:

app src  high-level structure

Above figure shows the structure and the heatmap about which parts of the systems have been changing most during the last year. Quire logically, the "extensions" is the part that has been extended during the recent year most. The good sign is that utils has been stable without changes.

app src main server  high-level structure

In Server area there seems to be certain cyclical dependencies, e.g.

restServer.ts -> routes -> utils -> restServer.ts

When running cycle detection, it seems that quite many dependencies would need to be cleaned in order to make this dependency graph acyclic on this level: (see those deps needing for removal/reversal with a highlighted orange color)

Client src design

The figure shows the dependencies between the code files in client/src. It also illustrates the problematic dependencies in the system in places where there are dependency cycles. The dependency cycles are here a clue about bad design and mixed responsibilities.

However, when taking a closer look at some direct cycles here, e.g. the relationship between ui and commands, it seems that the cycles do not exist on the file level, as seen in the below figure. So these sort of directory level cycles could be avoided with moving code files into suitable new directories that better match with the logical responsibility.

The cyclical relationship between ui and commands.

Critical Code Files, Top 15

Most critical code files based on the incoming dependency count:

The columns are: commit_count_365  (indicating none of the files have been changed during last 365 days), external_incoming_dependency_count (indicating the importance of the code file to the other files in the system, e.g. store.ts is the most important), and loc (Lines of Code), indicating the functionality/complexity of the code file.

As seen here, there are few critical files such as conversion.ts that have a high amount of source code (half KLOC) and still it is also highly reused within the system.

The criticality of store here indicates a global god state pattern. And when inspecting the two store.ts files, it seems those files have quite much in common, some sort of copy paste originally, and then tweaked apart. Those files need special care when changing.

The real concern here is that how much the two store.ts files do have plagued the system. Let's look at it with two colored views, one for each store.ts.

As seen,  the store impacts directly quite a large set of other components, but luckily majority of the system such as critical utils dir there, is independent from the store.

Another common threat is that utils/common/core kind of component starts with as such, but later becomes a god component that uses also many other components, leading into dependency hell situation. In this project that is cleanly managed, e.g. client utils is not having any direct or indirect dependency chains to the rest of the system except for mocks which is ok.

Burning Components based on Github Bug Labeled Issues

This picture highlights the fact that there are few code files that have been fixed plenty of times.

When looking at the clean commit count 365 metric, it seems that inspector.tsx has been highly changing recently. There is also one bug fixed there, and the author_count indicates nearly all of the active developers in the project have most likely been modifying that file. It clearly is some sort of bottleneck there, and has almost half KLOC of code, growing to be too much for the sufficient maintenance.

Most complex code files, Top 15

Below table shows LOC amongts other metrics to show the top 15 largest code files. It clearly indicates few code files needing to be splitted. Luckily many of those are spec.ts (not production code).

Dependencies

The dependency model contains 2313 elements and 2651 dependencies between the elements, quite a typical set for this sort of TypeScript project.

There are 6 code files that have > 17 external incoming dependencies. In order to show those, query @external_incoming_dependency_count  > 17 AND @type=file was used, together with dependency chain visualizations, but the produced view is too big to embed here. Contact the author for the model file to get it browsed in your Softagram Desktop app.

 

It is very critical for the future of the project that those 6 files shall be kept clean and not create too many outgoing dependencies into those files, otherwise the project will turn into a big hairy cyclical mess of dependencies.

Usage of copy paste coding (duplicate code checks)

Duplicate code situation is currently not analyzed since our tooling does not support copy paste detection for TypeScript. This is the situation with JavaScript code duplication in the project, these few files have been created using copy-paste coding.

Maintainability

Architectural limitations for further development

The system decomposition (directories and packages) is clean and understandable. It is easy to add new functionality into this sort of hierarchy.

There are some problems with poor naming, e.g. ui under client, which causes slowness and hesitation in software development work.

VULNERABILITIES

Based on scanning open source components from package.json, following components were found to have known vulnerabilities: (CVE IDs in the picture, go to nvd.dist.gov/vuln/detail/{ID} for more info.)

INTELLECTUAL PROPERTY AND OPEN SOURCE LICENSES

No 3rd party non-opensource IPRs detected.

All of the open source licenses are MIT, and plenty of code files in the codebase are spammed with MIT license header that also advertises Microsoft as the copyright holder.

Appendice

Ask support@softagram.com for the access to our downloadable resources where you get the access to the raw data related to this report.

For more information, see the analysis raw output files about all findings:

  1. Tech debt markers: attr_tech_debt_markers.csv
  2. Open source components: attr_licenses.csv
  3. A separate directory of hand-picked dependency and structural views of the system (PNG, SVG)
  4. Softagram model of the project  (modelfile.xml.zip and its related attribute files)
  5. Copy paste fragments and code duplication metrics: attr_pmd.csv

Remarks

Commit history data source is based on Git history. As it is possible to rewrite history in Git, it is not 100% reliable in all cases.