Repository files navigation

Plugin shows complexity information

This plugin implements live calculation of theCognitive Complexity metric,which was proposed by G. Ann Campbell inCognitive Complexity - A new way of measuring understandability(c) SonarSource S.A. 2016-2021, Switzerland.

Abstract: Cyclomatic Complexity was initially formulated as a measurementof the "testability and maintainability" of the control flow of a module.While it excels at measuring the former, its underlying mathematical model isunsatisfactory at producing a value that measures the latter. This white paperdescribes a new metric that breaks from the use of mathematical models toevaluate code in order to remedy Cyclomatic Complexity’s shortcomings andproduce a measurement that more accurately reflects the relative difficulty ofunderstanding, and therefore of maintaining methods, classes, and applications.

Table of Contents

• Code Metrics
  • 💾 Installation
    • 🔍 Method 1. withstraight.el anduse-package:
    • 🔍 Method 2. Manual
  • 🖥 Usage
    • 📚 Use it as a library
  • 🔨 Supported languages
  • 📝 Customization
    • ⚪ Analysis on new nodes
      • ❔ Example
    • 🔍 Writing new analysis functions
  • 🔗 References
  • 🛠️ Contribute
    • 🔬 Development
    • ❓ How to add an analysis rules?
      • 🔍 Where can I look for tree-sitter node?
  • ⚜️ License

(use-package codemetrics:straight (codemetrics:type git:host github:repo"jcs-elpa/codemetrics"))

git clone https://github.com/jcs-elpa/codemetrics /path/to/lib

then in Emacs:

(add-to-list'load-path"/path/to/lib")(require'codemetrics)

or

(use-package codemetrics:load-path"/path/to/lib")

The simplest way to start using this package:

(codemetrics-mode1)

These are functions you can use to analyze:

All these functions return the score data indicating the complexity.

⚠️ Please sort these two lists alphabetically!

These languages are fairly complete:

• Bash
• C / C++ / C#
• Elisp
• Go
• Java / JavaScript / JSX / Julia
• Kotlin
• Lua
• PHP / Python
• Ruby / Rust
• Swift
• TypeScript / TSX

These languages are in development:

• Agda
• Elm
• Elixir
• OCaml
• Scala (upstream, kinda buggy)

Although codemetrics aims to have good analysis rules out of the box for allsupported definitions, people will indubitably have their own preferences ordesired functionality. The following section outlines how to add your ownanalysis definitions and analysis functions to make codemetrics work for you.If there are any improvements you find for existing or new languages, please doraise a PR so that others may benefit from better analysis in the future!

Code-Metrics defines all its analysis definitions in the variablecodemetrics-rules which is an alist with the key of the alist being themode and the value being another alist of analysis definitions.

;; Example of codemetrics-rules' structure'((c-mode. c-analysis-definitions); <language>-analysis-definitions is structured as shown below  (csharp-mode. csharp-analysis-definitions)  (go-mode. go-analysis-definitions)  (scala-mode. scala-analysis-definitions)  ...);; Examle of a analysis definition alist(setq csharp-analysis-definitions    (if_statement. (1t))    ("&&". codemetrics-rules--logical-operators))

So you can select whatever node that you want to analyze on it.

To find what node you'll want to analyze, refer to thetree-sitter documentationabout viewing nodes.tree-sitter-debug andtree-sitter-query-builderare both very useful for this.

Let's look at a quick example of adding a new analysis definition. Let's say youwant to add analysis togo-mode'sif_statement. The analysis definition thatis needed will be'(if_statement . (1 t)). To add this to thecodemetrics-rules, you can do something like the following.

(push '(if_statement. (1t)) (alist-get'go-mode codemetrics-rules))

Now the new analysis definition should be usable by codemetrics!

For more complex analysis, you can write your own analysis rules!

• node - (optional) the targeted tree-sitter node, in this example,if_statement will be the targeting node.
• depth - (optional) current depth of from the root tree.
• nested - (optional) current nested level apply from current complexityalgorithm.

Then the function needs to return an integer represent the score and aboolean represent increment of the nested level in the form(score-to-add . nested?). This can be useful if you want to add extraconditional logic onto your analysis.

As an example of an analysis function, take a look at the definition of thebasiccodemetrics-rules--class-declaration.

(defuncodemetrics-rules--class-declaration (_nodedepth_nested)"..."  (codemetrics-with-complexity    (if (<1 depth); if class inside class,        '(1nil); we score 1, but don't increase nested level      '(0nil))    '(1nil)))

• codemetrics
• resharper-cognitivecomplexity
• gocognit

If you would like to contribute to this project, you may eitherclone and make pull requests to this repository. Or you canclone the project and establish your own branch of this tool.Any methods are welcome!

To run the test locally, you will need the following tools:

• Eask
• Make (optional)

Install all dependencies and development dependencies:

eask install-deps --dev

To test the package's installation:

eask packageeask install

To test compilation:

eask compile

🪧 The following steps are optional, but we recommend you follow these lint results!

The built-incheckdoc linter:

eask lint checkdoc

The standardpackage linter:

eask lint package

📝 P.S. For more information, find the Eask manual athttps://emacs-eask.github.io/.

When adding a new analysis rules, add the analysis definition function tocodemetrics.el itself near where the other rules functions live and then addthe parser tocodemetrics-rules.el file. Finally, if you are adding supportfor a new language, remember to add it to thecodemetrics-rules variable.

When creating a new parser, name itcodemetrics-rules-<language>.

When creating a new analysis function, name itcodemetrics-rules-<language>-<feature> or something similar.

Here are some techniques for finding your desired nodes in tree-sitter.

To look for the correct node you have three options:

• look at thetree-sitter-[lang]/grammar.js implementation. In the aboveexample,if_statement node is defined in thetree-sitter-c-sharp'sgrammar.js file
• open a file of your language choice in emacs andM-x tree-sitter-debug-mode.This will display the whole s-expr representing your file
• (message "%S" (tsc-node-to-sexp)) in your function to display what yourfunction is seeing

⚠️ Warning

Make sure you look into the correct repository. Repositories are managedundertree-sitter-langs'susing git submodule. Some tree-sitter module aren't using the latest version!

This program is free software; you can redistribute it and/or modifyit under the terms of the GNU General Public License as published bythe Free Software Foundation, either version 3 of the License, or(at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See theGNU General Public License for more details.

You should have received a copy of the GNU General Public Licensealong with this program. If not, seehttps://www.gnu.org/licenses/.

SeeLICENSE for details.