marvins

Marvins Code Quality Analyzer

Introduction

Marvins Code Quality Analyzer is a command-line tool designed to analyze TypeScript source files and provide valuable insights into your code's quality. By calculating several key metrics, Marvins helps developers identify potential issues, understand code complexity, and ensure maintainability.

The tool leverages the TypeScript compiler API to generate an Abstract Syntax Tree (AST), which is then traversed to compute various code quality metrics. These metrics include:

• Cyclomatic Complexity (CC)
• Halstead Volume (V)
• Lines of Code (LOC)
• Maintainability Index (MI)
• Comment Density (CD)

Code Quality Metrics

Cyclomatic Complexity (CC)

• Definition:
  Cyclomatic Complexity measures the number of linearly independent paths through a program's source code. It provides a quantitative measure of the program's decision structure.

Halstead Volume (V)

• Definition:
  Halstead Volume is derived from the number of operators and operands in the code. It represents the size of the implementation of an algorithm.

Lines of Code (LOC)

• Definition:
  LOC counts the total number of lines in a source file. While simple, it can be a useful indicator of code size and complexity.

Maintainability Index (MI)

• Definition:
  The Maintainability Index is a compound metric that provides an indication of how maintainable (or difficult to maintain) the code is.

Comment Density (CD)

• Definition:
  Comment Density is the ratio of comment lines to total lines of code, giving insight into how well the code is documented.

Abstract Syntax Tree (AST)

An Abstract Syntax Tree (AST) is a tree representation of the abstract syntactic structure of source code. Each node in the tree denotes a construct in the source code. In Marvins, the TypeScript compiler API is used to generate an AST from a source file. This AST is then traversed to:

• Identify decision points (e.g., conditional statements, loops) for calculating Cyclomatic Complexity.
• Analyze tokens to count operators and operands for Halstead Volume.
• Extract methods and functions to compute individual metrics.

Using the AST allows Marvins to perform a detailed and accurate analysis of code structure and quality.

Command-Line Interface (CLI)

Marvins is operated entirely via the command line. The CLI supports several commands to configure thresholds, update multipliers, and perform analysis on TypeScript files.

Configuration File

Marvins uses a config.json file located in the current working directory to store default thresholds and multipliers. If this file does not exist, it is automatically created with the following default values:

{
  "cyclomatic": { "medium": 6, "high": 10 },
  "maintainabilityIndex": { "low": 40, "medium": 60 },
  "loc": { "medium": 30, "high": 50 },
  "commentDensityMultiplier": 5
}

CLI Commands and Usage

1. Help Command

marvins help

• Description:
  Displays the help message with detailed information about available commands and usage examples.

2. Configure Command

Marvins provides two configuration options:

a. Update Metric Thresholds

marvins configure -t <metric> <value1> <value2>

• Parameters:

  • <metric>: The metric to update. Valid options are:
    • cyclomatic
    • maintainabilityIndex
    • loc
  • <value1>: The first threshold value (e.g., "medium" for cyclomatic or LOC, "low" for maintainabilityIndex).
  • <value2>: The second threshold value (e.g., "high" for cyclomatic or LOC, "medium" for maintainabilityIndex).

• Example:

  marvins configure -t cyclomatic 6 10
  

  This updates the cyclomatic complexity thresholds to a medium value of 6 and a high value of 10.

b. Update Comment Density Multiplier

marvins configure -d <value>

• Parameters:

  • <value>: A numeric value that updates the comment density multiplier used in the MI calculation.

• Example:

  marvins configure -d 7
  

  This updates the comment density multiplier to 7.

3. Analyze Command

marvins analyze -f {typescript filePath}

• Parameters:

  • {typescript filePath}: Path to the TypeScript file you wish to analyze.

• Description:
  Analyzes the specified TypeScript file and displays the computed metrics, including:

  • Calculated Comment Density.
  • Cyclomatic Complexity.
  • Halstead Volume.
  • Lines of Code.
  • Maintainability Index.

• Example:

  marvins analyze -f src/app.ts
  

  This command analyzes the src/app.ts file and outputs the analysis results.

Conclusion

Marvins Code Quality Analyzer is a powerful tool that leverages static analysis and AST traversal to provide insights into code quality. By monitoring metrics such as Cyclomatic Complexity, Halstead Volume, Lines of Code, Maintainability Index, and Comment Density, developers can better understand and improve their codebase.

For further information or assistance, simply run:

marvins help

Enjoy using Marvins to keep your code clean, maintainable, and of high quality!