Compose Compiler Reports to HTML Generator

A utility (Gradle Plugin + CLI) to convert Jetpack Compose compiler metrics and reports to beautified HTML page.

Description

A CLI utility to convert Jetpack Compose compiler metrics and reports to beautified 😍 HTML page. Made with ❤️ for Android Developers and Composers

Programming language: Kotlin

License: MIT License

Tags: Kotlin     Android     Compose     Cli     Metrics     Reports    

README

Compose Compiler Reports to HTML Generator

A CLI utility to convert Jetpack Compose compiler metrics and reports to beautified 😍 HTML page. Made with ❤️ for Android Developers and Composers

	Install	Downloads
NPM
JAR

💡 Motivation

The Compose Compiler plugin can generate reports / metrics around certain compose-specific concepts that can be useful to understand what is happening with some of your compose code at a fine-grained level. See this.

This generates reports in json, csv and txt files which are not easily trace-able for developers. Also, Composable function and class reports becomes large and tedious to check. This tool parses the reports and metrics generated by Compose compiler and beautifies into a HTML page and intelligently distinguishes problematic and non-problematic composable functions and classes.

This utility doesn't generate Compose Metrics and Reports. First, raw Compose report should be generated from the Compiler and those generated files should be feed to this utility. By parsing that data, this utility generates the beautified report.

🧑‍💻 Usage

First, install the CLI utility

1. Install CLI

To install the CLI utility, there are two ways

1.1 Directly use .jar distribution

Navigate to the releases and download the latest JAR artifact.

1.2 Install from NPM

Install the NPM package for CLI utility.

npm install -g compose-report2html

2. Know usage

Run the commands to know the usage of CLI

2.1 If using JAR artifact

java -jar composeReport2Html.jar -h

2.2 If using NPM package

If you have installed CLI utility from NPM package, it can be directly available from Terminal.

composeReport2Html -h

Once you run, here's how it looks.

Usage: Compose Compiler Report to HTML Generator options_list
Options:
    --applicationName, -app -> Application name (To be displayed in the report) (always required) { String }
    --overallStatsFile, -overallStatsReport -> Overall Statistics Metrics JSON file (always required) { String }
    --detailedStatsFile, -detailedStatsMetrics -> Detailed Statistics Metrics CSV file (always required) { String }
    --composableMetricsFile, -composableMetrics -> Composable Metrics TXT file (always required) { String }
    --classMetricsFile, -classMetrics -> Class Metrics TXT file (always required) { String }
    --outputDirectory, -o -> Output directory name (always required) { String }
    --help, -h -> Usage info

3. Generate report

Make sure to generate Compose compiler metrics and reports as mentioned here or this good read article by Chris Banes. These files are then needed to this CLI utility to feed the data.

To generate the report, provide details related to app, metric and report files and output directory.

java -jar composeReport2Html.jar \
  -app <YOUR_APP_NAME> \
  -overallStatsReport <PATH TO *-module.json FILE> \
  -detailedStatsMetrics <PATH TO *-composables.csv FILE> \
  -composableMetrics <PATH TO *-composables.txt FILE> \
  -classMetrics <PATH TO *-classes.txt FILE> \
  -o <OUTPUT DIRECTORY PATH FOR REPORT>

OR, directly use composeReport2Html (if using NPM package).

Example Usage:

java -jar composeReport2Html.jar \
  -app NotyKT \
  -overallStatsReport app_release-module.json \
  -detailedStatsMetrics app_release-composables.csv \
  -composableMetrics app_release-composables.txt \
  -classMetrics app_release-classes.txt \
  -o notyReport

In the above example, it will create report with name "NotyKT" with specified metric and report files and finally report will be generated in the specified path i.e. notyReport/index.html.

📈 Report Overview

Once report is generated, it looks like this.

Title	Preview
Brief Statistics	Generates metrics from .json file and represents in tabular format. [Brief Statistics](images/brief-stats.png)
Detailed Statistics	Generates report from .csv file and represents in tabular format. [Detailed Statistics](images/detailed-stats.png)
Composable Report	Parses -composables.txt file and separates out composables with and without issues and properly highlights issues associated with them. [Composable Report](images/composable-report.png)
Class Report	Parses -classes.txt file and separates out stable and unstable classes out of it and properly highlights issues associated with them. [Class Report](images/class-report.png)

Right now, work is in progress and more improvements related to the report will happen in some time. If you have any feedback / suggestions related to the report, feel free to discuss it (find discussion link in the below section).

🙋‍♂️ Contribute

Read [contribution guidelines](CONTRIBUTING.md) for more information regarding contribution.

💬 Discuss?

Have any questions, doubts or want to present your opinions, views? You're always welcome. You can start discussions.

License

MIT License

Copyright (c) 2022 Shreyas Patil

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.