Add mdbook site (#176)
* Add mdbook * Add a script to automatically deploy Github Pages * Update README * Add link to documentation * Clarify a statement * Refactor Rest API page * Add a section to explain how to count errors
This commit is contained in:
Luni-4
GitHub
Родитель
9c723f0017
Коммит
c411a7a4c3
121
README.md
121
README.md
|
|
@ -6,99 +6,48 @@
|
|||
<img src="https://img.shields.io/badge/chat%20on%20[m]-%23rust--code--analysis%3Amozilla.org-blue">
|
||||
</a>
|
||||
|
||||
**rust-code-analysis** is a Rust library to analyze the source code of many different programming languages. It is based on a parser generator tool and an incremental parsing library called [Tree Sitter](https://github.com/tree-sitter/tree-sitter).
|
||||
|
||||
## Supported Languages
|
||||
|
||||
* C++
|
||||
* C#
|
||||
* CSS
|
||||
* Go
|
||||
* HTML
|
||||
* Java
|
||||
* JavaScript
|
||||
* The JavaScript used in Firefox internal
|
||||
* Python
|
||||
* Rust
|
||||
* Typescript
|
||||
|
||||
## Supported Metrics
|
||||
|
||||
- CC: it calculates the code complexity examining the
|
||||
control flow of a program.
|
||||
- SLOC: it counts the number of lines in a source file.
|
||||
- PLOC: it counts the number of physical lines (instructions) contained in a source file.
|
||||
- LLOC: it counts the number of logical lines (statements) contained in a source file.
|
||||
- CLOC: it counts the number of comments in a source file.
|
||||
- BLANK: it counts the number of blank lines in a source file.
|
||||
- HALSTEAD: it is a suite that provides a series of information, such as the effort required to maintain the analyzed code, the size in bits to store the program, the difficulty to understand the code, an estimate of the number of bugs present in the codebase, and an estimate of the time needed to implement the software.
|
||||
- MI: it is a suite that allows to evaluate the maintainability of a software.
|
||||
- NOM: it counts the number of functions and closures in a file/trait/class.
|
||||
- NEXITS: it counts the number of possible exit points from a method/function.
|
||||
- NARGS: it counts the number of arguments of a function/method.
|
||||
|
||||
# rust-code-analysis-cli
|
||||
|
||||
**rust-code-analysis-cli** is a command line tool thought to interact with
|
||||
the functions available in the library.
|
||||
It can print a series of information on your shell such as nodes and metrics.
|
||||
It can also export metrics as a json file.
|
||||
Below you can find a series of commands to use the software at best.
|
||||
|
||||
### How to get metrics
|
||||
|
||||
You can get metrics in your shell in this way
|
||||
|
||||
```
|
||||
rust-code-analysis-cli --metrics --paths /your/path/to/a/file
|
||||
```
|
||||
|
||||
or as a `json` file
|
||||
|
||||
```
|
||||
rust-code-analysis-cli --metrics --output your/path/to/the/output/directory --paths /your/path/to/a/file
|
||||
```
|
||||
|
||||
or you can run it as a `HTTP` service and use its `REST API`
|
||||
**rust-code-analysis** is a Rust library to analyze and extract information
|
||||
from source codes written in many different programming languages.
|
||||
It is based on a parser generator tool and an incremental parsing library
|
||||
called
|
||||
<a href="https://tree-sitter.github.io/tree-sitter/" target="_blank">
|
||||
Tree Sitter
|
||||
</a>.
|
||||
|
||||
|
||||
```
|
||||
rust-code-analysis --serve --port 9090
|
||||
```
|
||||
In addition, we provide a command line tool called **rust-code-analysis-cli**
|
||||
to interact with the API of the library in an easy way.
|
||||
|
||||
This tool can be used to:
|
||||
|
||||
## How to build the software
|
||||
- Call **rust-code-analysis** API
|
||||
- Print nodes and metrics information
|
||||
- Export metrics in different formats
|
||||
|
||||
Clone the repository and its submodules through HTTPS
|
||||
# Software Usability
|
||||
|
||||
```
|
||||
git clone --recurse-submodules -j8 https://github.com/mozilla/rust-code-analysis.git
|
||||
```
|
||||
**rust-code-analysis** supports many types of programming languages and
|
||||
computes a great variety of metrics. If you want to discover more on this
|
||||
software, read our
|
||||
<a href="https://mozilla.github.io/rust-code-analysis/index.html" target="_blank">
|
||||
Documentation
|
||||
</a>.
|
||||
|
||||
or through SSH
|
||||
On the
|
||||
<a href="https://mozilla.github.io/rust-code-analysis/commands/index.html" target="_blank">
|
||||
Commands
|
||||
</a> page, you will learn which commands need to be run to get information
|
||||
about metrics, nodes, and other general data provided by this software.
|
||||
|
||||
```
|
||||
git clone --recurse-submodules -j8 git@github.com:mozilla/rust-code-analysis.git
|
||||
```
|
||||
If you want to contribute to the development of this software
|
||||
or you are just interested in building **rust-code-analysis**, have a look at the
|
||||
<a href="https://mozilla.github.io/rust-code-analysis/developers/index.html" target="_blank">
|
||||
Developers Guide
|
||||
</a>.
|
||||
|
||||
Build and run the software
|
||||
# License
|
||||
|
||||
```console
|
||||
# Build rust-code-analysis with cargo
|
||||
cargo build
|
||||
|
||||
# Build rust-code-analysis-cli with cargo
|
||||
cargo build --all
|
||||
|
||||
# Run through cargo
|
||||
cargo run -- -h
|
||||
cargo run -- --serve --port 8000
|
||||
```
|
||||
|
||||
## How to run tests
|
||||
|
||||
After the build step, run the following command to verify if all tests pass
|
||||
|
||||
```
|
||||
cargo test --verbose
|
||||
```
|
||||
All the source code of **rust-code-analysis** is released under the
|
||||
<a href="https://www.mozilla.org/MPL/2.0/" target="_blank">
|
||||
Mozilla Public License v2.0
|
||||
</a>.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,3 @@
|
|||
book
|
||||
src/debug/*
|
||||
src/.rustc_info.json
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
[book]
|
||||
title = "Rust-Code-Analysis Documentation"
|
||||
description = "This book documents rust-code-analysis"
|
||||
authors = ["Calixte Denizet <cdenizet@mozilla.com>"]
|
||||
language = "en"
|
||||
|
||||
[output.html]
|
||||
mathjax-support = true
|
||||
|
||||
[output.html.playpen]
|
||||
line-numbers = true
|
||||
|
||||
[output.html.search]
|
||||
limit-results = 25
|
||||
use-boolean-and = true
|
||||
boost-title = 2
|
||||
boost-hierarchy = 2
|
||||
boost-paragraph = 1
|
||||
expand = true
|
||||
heading-split-level = 3
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
#!/bin/sh
|
||||
|
||||
[ -d /tmp/book ] || (git worktree prune && git branch -D gh-pages)
|
||||
|
||||
git worktree add -b gh-pages /tmp/book
|
||||
mdbook build
|
||||
rm -rf /tmp/book/* # this won't delete the .git directory
|
||||
cp -rp book/* /tmp/book/
|
||||
cd /tmp/book
|
||||
git add -A
|
||||
git commit -m "Deploy rust-code-analysis"
|
||||
git push -f origin gh-pages
|
||||
|
|
@ -0,0 +1,81 @@
|
|||
# rust-code-analysis
|
||||
|
||||
**rust-code-analysis** is a Rust library to analyze and extract information
|
||||
from source codes written in many different programming languages.
|
||||
It is based on a parser generator tool and an incremental parsing library
|
||||
called
|
||||
<a href="https://tree-sitter.github.io/tree-sitter/" target="_blank">Tree Sitter</a>.
|
||||
|
||||
You can find the source code of this software on
|
||||
<a href="https://github.com/mozilla/rust-code-analysis/" target="_blank">GitHub</a>,
|
||||
while issues and feature requests can be posted on the respective
|
||||
<a href="https://github.com/mozilla/rust-code-analysis/issues/" target="_blank">GitHub Issue Tracker</a>.
|
||||
|
||||
## Supported Languages
|
||||
|
||||
Below you can find the list of programming languages parsed by
|
||||
**rust-code-analysis**.
|
||||
|
||||
* C++
|
||||
* C#
|
||||
* CSS
|
||||
* Go
|
||||
* HTML
|
||||
* Java
|
||||
* JavaScript
|
||||
* The JavaScript used in Firefox internal
|
||||
* Python
|
||||
* Rust
|
||||
* Typescript
|
||||
|
||||
## Supported Metrics
|
||||
|
||||
**rust-code-analysis** implements a series of metrics
|
||||
- **CC**: it calculates the code complexity examining the
|
||||
control flow of a program.
|
||||
- **SLOC**: it counts the number of lines in a source file.
|
||||
- **PLOC**: it counts the number of physical lines (instructions) contained in
|
||||
a source file.
|
||||
- **LLOC**: it counts the number of logical lines (statements) contained in
|
||||
a source file.
|
||||
- **CLOC**: it counts the number of comments in a source file.
|
||||
- **BLANK**: it counts the number of blank lines in a source file.
|
||||
- **HALSTEAD**: it is a suite that provides a series of information, such as the
|
||||
effort required to maintain the analyzed code, the size in bits to store the
|
||||
program, the difficulty to understand the code, an estimate of the number of
|
||||
bugs present in the codebase, and an estimate of the time needed to
|
||||
implement the software.
|
||||
- **MI**: it is a suite that allows to evaluate the maintainability of a software.
|
||||
- **NOM**: it counts the number of functions and closures in a file/trait/class.
|
||||
- **NEXITS**: it counts the number of possible exit points from a method/function.
|
||||
- **NARGS**: it counts the number of arguments of a function/method.
|
||||
|
||||
The metrics above are still **NOT** implemented for C#, CSS, Go, HTML, and Java
|
||||
languages.
|
||||
|
||||
## Supported platforms
|
||||
|
||||
**rust-code-analysis** can run on the most common platforms: Linux, macOS,
|
||||
and Windows.
|
||||
|
||||
On our
|
||||
<a href="https://github.com/mozilla/rust-code-analysis/releases" target="_blank">
|
||||
GitHub Release Page
|
||||
</a> you can find the `Linux` and `Windows` binaries already compiled and
|
||||
packed for you.
|
||||
|
||||
|
||||
## API docs
|
||||
|
||||
If you prefer to use **rust-code-analysis** as a crate, you can find the
|
||||
`API docs` generated by `Rustdoc`
|
||||
<a href="https://docs.rs/rust-code-analysis/*/rust-code-analysis/" target="_blank">
|
||||
here
|
||||
</a>.
|
||||
|
||||
## License
|
||||
|
||||
All the source code of **rust-code-analysis** is released under the
|
||||
<a href="https://www.mozilla.org/MPL/2.0/" target="_blank">
|
||||
Mozilla Public License v2.0
|
||||
</a>.
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
# Summary
|
||||
|
||||
- [rust-code-analysis](./README.md)
|
||||
- [Commands](commands/README.md)
|
||||
- [Metrics](commands/metrics.md)
|
||||
- [Nodes](commands/nodes.md)
|
||||
- [Rest API](commands/rest.md)
|
||||
- [Developers Guide](developers/README.md)
|
||||
|
|
@ -0,0 +1,64 @@
|
|||
# Commands
|
||||
|
||||
With the term **command**, we define any procedure used by
|
||||
**rust-code-analysis-cli** to extract information from source codes.
|
||||
At each command **may** be associated parameters depending on the task
|
||||
it needs to carry out.
|
||||
In this page we have grouped the principal **types** of commands implemented in
|
||||
**rust-code-analysis-cli**.
|
||||
|
||||
## Metrics
|
||||
|
||||
Metrics are a series of measures that can be used to:
|
||||
|
||||
- Compare different programming languages
|
||||
- Provide information on the quality of a code
|
||||
- Tell developers where their code is more tough to handle
|
||||
- Discover errors earlier
|
||||
|
||||
**rust-code-analysis** calculates the metrics starting from the
|
||||
source code of a program. These kind of metrics are called *static metrics*.
|
||||
|
||||
The list of metrics supported right now are the following ones:
|
||||
|
||||
- **CC**: it calculates the code complexity examining the
|
||||
control flow of a program.
|
||||
- **SLOC**: it counts the number of lines in a source file.
|
||||
- **PLOC**: it counts the number of physical lines (instructions) contained in
|
||||
a source file.
|
||||
- **LLOC**: it counts the number of logical lines (statements) contained in
|
||||
a source file.
|
||||
- **CLOC**: it counts the number of comments in a source file.
|
||||
- **BLANK**: it counts the number of blank lines in a source file.
|
||||
- **HALSTEAD**: it is a suite that provides a series of information, such as the
|
||||
effort required to maintain the analyzed code, the size in bits to store the
|
||||
program, the difficulty to understand the code, an estimate of the number of
|
||||
bugs present in the codebase, and an estimate of the time needed to
|
||||
implement the software.
|
||||
- **MI**: it is a suite that allows to evaluate the maintainability of a software.
|
||||
- **NOM**: it counts the number of functions and closures in a file/trait/class.
|
||||
- **NEXITS**: it counts the number of possible exit points from a method/function.
|
||||
- **NARGS**: it counts the number of arguments of a function/method.
|
||||
|
||||
## Nodes
|
||||
|
||||
To represent the structure of program code, **rust-code-analysis-cli** builds
|
||||
an
|
||||
<a href="https://en.wikipedia.org/wiki/Abstract_syntax_tree" target="_blank">Abstract Syntax Tree (AST)</a>.
|
||||
A **node** is an element of this tree and denotes any syntactic construct
|
||||
present in a language.
|
||||
|
||||
Nodes can be used to:
|
||||
|
||||
- Create the syntactic structure of a source file
|
||||
- Discover if a construct of a language is present in the analyzed
|
||||
code
|
||||
- Count the number of constructs of a certain kind
|
||||
- Detect errors i the source code
|
||||
|
||||
## REST API
|
||||
|
||||
**rust-code-analysis-cli** can be run as a server which accepts requests sent
|
||||
through `REST API`.
|
||||
The server receives in input the filename of a source code file and returns the
|
||||
relative metrics formatted as a `json` file.
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
# Metrics
|
||||
|
||||
Metrics can be printed on screen or exported as different output formats
|
||||
through **rust-code-analysis-cli**.
|
||||
|
||||
## Print metrics
|
||||
|
||||
For each function space, **rust-code-analysis** computes the list of metrics
|
||||
described above. At the end of this process, **rust-code-analysis-cli**
|
||||
dumps the result formatted in a certain way on the screen.
|
||||
The command used to print the metrics is the following one:
|
||||
|
||||
```console
|
||||
rust-code-analysis-cli -m -p /path/to/your/file/or/directory
|
||||
```
|
||||
|
||||
The `-p` option represents the path to a file or a directory. If a directory is
|
||||
passed as input, **rust-code-analysis-cli** computes the metrics for each file
|
||||
contained in it.
|
||||
|
||||
## Export formats
|
||||
|
||||
Different output formats can be used to export metrics:
|
||||
|
||||
- Cbor
|
||||
- Json
|
||||
- Toml
|
||||
- Yaml
|
||||
|
||||
`Json` and `Toml` can also be exported pretty-printed.
|
||||
|
||||
### Export command
|
||||
|
||||
For example, if you want to export metrics as a `json` file, run:
|
||||
|
||||
```console
|
||||
rust-code-analysis-cli -m -O json -o /output/path -p /path/to/your/file/or/directory
|
||||
```
|
||||
|
||||
The `-O` option allows you to choose the output format. It supports
|
||||
**only** these values: *cbor*, *json*, *toml*, *yaml*.
|
||||
|
||||
The `-o` option is used to specify the path where your file will be saved.
|
||||
It accepts **only** paths. The filename of your output file is the same as
|
||||
your input file plus the extension associated to the format. When this option
|
||||
is not given, the output is printed on shell.
|
||||
|
||||
As we said before, `Json` and `Toml` can be exported as pretty-printed. To do
|
||||
so, the `--pr` option is used.
|
||||
In the case below, the pretty-printed `json` output will be printed on shell:
|
||||
|
||||
```console
|
||||
rust-code-analysis-cli -m -O json --pr -p /path/to/your/file/or/directory
|
||||
```
|
||||
|
|
@ -0,0 +1,52 @@
|
|||
# Nodes
|
||||
|
||||
**rust-code-analysis-cli** allows to extract some information from the nodes
|
||||
which compose the *Abstract Syntax Tree (AST)* of a source code.
|
||||
|
||||
## Find Errors
|
||||
|
||||
To know if there are some syntactic errors in your code, run:
|
||||
|
||||
```console
|
||||
rust-code-analysis-cli -p /path/to/your/file/or/directory -I "*.ext" -f -error
|
||||
```
|
||||
|
||||
The `-p` option represents the path to a file or a directory. If a directory is
|
||||
passed as input, **rust-code-analysis-cli** computes the metrics for each file
|
||||
contained in it.
|
||||
The `-I` option is a glob filter used to consider only the files written in
|
||||
the language defined by the extension of the file.
|
||||
The `-f` option instead searches all nodes of a certain type.
|
||||
In the case above, we are looking for all the erroneous nodes present in the
|
||||
code.
|
||||
|
||||
## Count Errors
|
||||
|
||||
It is also possible to count the number of nodes of a certain type using the
|
||||
`--count` option:
|
||||
|
||||
```console
|
||||
rust-code-analysis-cli -p /path/to/your/file/or/directory -I "*.ext" --count -error
|
||||
```
|
||||
|
||||
## Print AST
|
||||
|
||||
If you want to print the AST of a source code, run the following command:
|
||||
|
||||
```console
|
||||
rust-code-analysis-cli -p /path/to/your/file/or/directory -d
|
||||
```
|
||||
|
||||
The `-d` option prints the entire AST on the shell.
|
||||
|
||||
## Code Splitting
|
||||
|
||||
Commands can be run on a single portion of the code using the `--ls`
|
||||
and `--le` options. The former represents the starting line of the code to be
|
||||
considered, while the latter its ending line.
|
||||
For example, if we want to print the AST of a single function which starts at
|
||||
line 5 and ends at line 10, we need to launch this command:
|
||||
|
||||
```console
|
||||
rust-code-analysis-cli -p /path/to/your/file/or/directory -d --ls 5 --le 10
|
||||
```
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
# Rest API
|
||||
|
||||
It is possible to run **rust-code-analysis-cli** as a `HTTP` service using
|
||||
`REST API` to share data between client and server.
|
||||
We will use the port `9090` to show you the possible ways to
|
||||
interact with the server.
|
||||
|
||||
## Server
|
||||
|
||||
**rust-code-analysis-cli** can act as a server running on your `localhost`
|
||||
at a specific port.
|
||||
|
||||
```
|
||||
rust-code-analysis-cli --serve --port 9090
|
||||
```
|
||||
|
||||
The `--port` option sets the port used by the server. One possible value
|
||||
could be `9090`.
|
||||
|
||||
## Ping
|
||||
|
||||
If you want to ping the server, make a `GET` request at this `URL`:
|
||||
|
||||
```
|
||||
http://127.0.0.1:9090/ping
|
||||
```
|
||||
|
||||
## Metrics
|
||||
|
||||
To get metrics formatted as a `json` file, make a `POST` request at this `URL`:
|
||||
|
||||
```
|
||||
http://127.0.0.1:9090/metrics?file_name={filename}&unit={unit}
|
||||
```
|
||||
|
||||
The `filename` parameter represents the path to the source file to be analyzed,
|
||||
while `unit` is a boolean value that can assume only `0` or `1`. The latter
|
||||
tells **rust-code-analysis-cli** to consider only top-level metrics, while the
|
||||
former returns detailed metrics for all classes, functions, nested functions,
|
||||
and other sub-spaces.
|
||||
|
|
@ -0,0 +1,127 @@
|
|||
# Developers Guide
|
||||
|
||||
If you want to contribute to the development of `rust-code-analysis` we have
|
||||
summarized here a series of guidelines that are supposed to help you in your
|
||||
building process.
|
||||
|
||||
As prerequisite, you need to install the last available version of `Rust`.
|
||||
You can learn how to do that
|
||||
<a href="https://www.rust-lang.org/tools/install" target="_blank">
|
||||
here
|
||||
</a>.
|
||||
|
||||
## Clone Repository
|
||||
|
||||
First of all, you need to clone the repository and all of its submodules.
|
||||
You can do that:
|
||||
|
||||
through **HTTPS**
|
||||
|
||||
```
|
||||
git clone --recurse-submodules -j8 https://github.com/mozilla/rust-code-analysis.git
|
||||
```
|
||||
|
||||
or through **SSH**
|
||||
|
||||
```
|
||||
git clone --recurse-submodules -j8 git@github.com:mozilla/rust-code-analysis.git
|
||||
```
|
||||
|
||||
## Building
|
||||
|
||||
To build the `rust-code-analysis` library, you need to run the following
|
||||
command:
|
||||
|
||||
```console
|
||||
cargo build
|
||||
```
|
||||
|
||||
If you are also interested in the cli tool:
|
||||
|
||||
```console
|
||||
cargo build --all
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
After you have finished changing the code, you should **always** verify whether
|
||||
all tests pass with the `cargo test` command.
|
||||
|
||||
```console
|
||||
cargo test --all-features --verbose
|
||||
```
|
||||
|
||||
## Code Formatting
|
||||
|
||||
If all previous steps went well, and you want to make a pull request
|
||||
to integrate your invaluable help in the codebase, the last step left is
|
||||
code formatting.
|
||||
|
||||
### Rustfmt
|
||||
|
||||
This tool formats your code according to Rust style guidelines.
|
||||
|
||||
To install:
|
||||
|
||||
```console
|
||||
rustup component add rustfmt
|
||||
```
|
||||
|
||||
To format the code:
|
||||
|
||||
```console
|
||||
cargo fmt
|
||||
```
|
||||
|
||||
### Clippy
|
||||
|
||||
This tool helps developers to write better code catching automatically lots of
|
||||
common mistakes for them. It detects in your code a series of errors and
|
||||
warnings that **must** be fixed before making a pull request.
|
||||
|
||||
To install:
|
||||
|
||||
```console
|
||||
rustup component add clippy
|
||||
```
|
||||
|
||||
To detect errors and warnings:
|
||||
|
||||
```console
|
||||
cargo clippy --all-targets --all --
|
||||
```
|
||||
|
||||
## Code Documentation
|
||||
|
||||
If you have documented your code, to generate the final documentation,
|
||||
run this command:
|
||||
|
||||
```console
|
||||
cargo doc --all-features --no-deps
|
||||
```
|
||||
|
||||
Remove the `--no-deps` option if you also want to build the documentation of
|
||||
each dependency used by **rust-code-analysis**.
|
||||
|
||||
## Run your code
|
||||
|
||||
You can run **rust-code-analysis-cli** using:
|
||||
|
||||
```console
|
||||
cargo run -- [rust-code-analysis-cli-parameters]
|
||||
```
|
||||
|
||||
To know the list of **rust-code-analysis-cli** parameters, run:
|
||||
|
||||
```console
|
||||
cargo run -p rust-code-analysis-cli -- --help
|
||||
```
|
||||
|
||||
## Practical advice
|
||||
|
||||
- When you add a new feature, add at least one unit or integration test to
|
||||
verify that everything works correctly
|
||||
- Document public API
|
||||
- Do not add dead code
|
||||
- Comment intricate code such that others can comprehend what you have
|
||||
accomplished
|
||||
Загрузка…
Ссылка в новой задаче