SOFTAGRAM AUDIT: BotFramework-Emulator

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

General overview

Recommendations

Architectural Quality & Architecture Views

Systems Decomposition

The target of the analysis consists of a single emulator system. Its structure is described in the following paragraphs.

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)

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.

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.

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.

Code Quality & Maintainability

Code quality was analyzed with xx…..

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).

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

• Estimated technical debt

• There are technical debt markers (TODO-comments, FIXME-comments, xxx etc.) in the software, in both frontend and backend code.. Total number of those is very low. The low number usually means the original developers have been involved in the project and not much competence transfer has been needed.

• Development vs. bugfix rate

• Rate of fixing is low, only 23 % of the commits (during one year) is related to bug fixes. This might indicate two different things: 1) there has been new development, but not much work in fixing old bugs.  2) There are no bugs, and also new development does not create many bugs.

• Complexity

• Some of the code comments (related to tech debt search) imply that the specification work is not thoroughly completed before development.
• The business domain of the product is complex, which makes it difficult to write simple software for it.
• The state management using Store is challenging and might cause trouble for new developers. We recommend to create clarifying documentation about it.

• Refactoring recommendations

• The biggest code files should be refactored to have just one responsibility, making it easier to continue and to avoid the god class anti pattern.

Security & Open Source Risks

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.