ink-analyzer/ink-analyzer

A collection of modular and reusable libraries and tools for semantic analysis of ink! smart contracts.

ink! Analyzer

A collection of modular and reusable libraries and tools for semantic analysis of ink! smart contracts.

ink! analyzer aims to improve ink! language support in integrated development environments (IDEs), source code editors and other development tools by providing modular and reusable building blocks for implementing features like diagnostics, code completion, code/intent actions and hover content for the ink! programming language which is used for writing smart contracts for blockchains built with Substrate.

• Introductory blog post.

Architecture

This repository contains 4 main crates:

1. Semantic Analyzer (ink-analyzer)

This crate implements utilities for performing semantic analysis of ink! smart contract code. It therefore implements the core functionality of ink! analyzer at a high level.

It currently implements an Analysis entry point that accepts a string representation (&str) of ink! smart contract code as input and defines associated methods that compute:

• diagnostics - errors and warnings based on ink! semantic rules.
• quickfixes - suggested edits/code actions for diagnostic errors and warnings.
• completions - completion suggestions for ink! attribute macros, arguments and entities/items.
• code/intent actions - contextual assists for:
  • adding relevant ink! attribute macros, arguments and entities/items
  • migrating ink! projects to newer versions of ink! (e.g. ink! 4.x to 5.0)
  • extracting ink! entities (e.g. ink! 5.0 events) into standalone packages
  • and more!
• hover content - descriptive/informational text for ink! attribute macros and arguments.
• inlay hints - inline type and format information for ink! attribute arguments values (e.g. u32 | _ | @ for ink! message selectors).
• signature help - popup information for valid ink! attribute arguments for the current context/cursor position.

2. Language Server (ink-lsp-server)

This crate implements the Language Server Protocol (LSP) and acts as a backend that provides language support features like diagnostic errors, code completion suggestions, code/intent actions and hover content to IDEs, code editors and other development tools.

It uses the semantic analyzer as the engine for providing ink! language support features by:

• translating LSP requests into semantic analyzer interface calls.
• translating semantic analysis results into corresponding LSP types.

It additionally uses rust-analyzer's lsp-server crate to handle LSP protocol handshaking and parsing messages, and the lsp-types crate for LSP type definitions.

Its compiled binary can be used with any LSP client that can be configured to launch an LSP server using an executable command (i.e. the path to the ink-lsp-server binary) and can use stdio (standard in/standard out) as the message transport.

3. IR (ink-analyzer-ir)

This crate implements types, abstractions and utilities for parsing ink! smart contract code into ink! intermediate representations (IRs) and abstractions.

It implements types and abstractions for all ink! entities (e.g contracts, storage, events, topics, impls, constructors, messages, selectors, tests, trait definitions, chain extensions, storage items e.t.c).

It uses rust-analyzer's ra_ap_syntax crate for generating the syntax tree of the ink! smart contract code that it then converts into ink! entity intermediate representations and abstractions.

It uses ra_ap_syntax instead of other Rust parsing and syntax tree libraries because ink! analyzer has similar design goals to rust-analyzer. The most important being that parsing should be:

• resilient (even if the input is invalid, parser tries to see as much syntax tree fragments in the input as it can).
• lossless (even if the input is invalid, the tree produced by the parser represents it exactly).

It's the main dependency for the semantic analyzer crate.

4. Proc-macros (ink-analyzer-macro)

This crate implements procedural macros used primarily by the ink-analyzer-ir crate.

Installation and Usage

Check the readme of each crate for installation and usage instructions and links to documentation.

• Semantic Analyzer: /crates/analyzer
• Language Server: /crates/lsp-server
• IR: /crates/ir
• Proc-macros: /crates/macro

Documentation

• Semantic Analyzer: https://docs.rs/ink-analyzer/latest/ink_analyzer/
• Language Server: https://docs.rs/ink-lsp-server/latest/ink_lsp_server/
• IR: https://docs.rs/ink-analyzer-ir/latest/ink_analyzer_ir/
• Proc-macros: https://docs.rs/ink-analyzer-macro/latest/ink_analyzer_macro/

Or you can access documentation locally by running the following command from the project root

cargo doc --open

To open crate specific docs, see instructions in the readme in each crate's directory.

Testing

You can run unit and integration tests for all the core functionality for all crates by running the following command from the project root

Option 1: Native Rust and cargo

cargo test

NOTE: To run only tests for a single crate, add a -p <crate_name> argument to the above command e.g.

cargo test -p ink-analyzer-ir

Option 2: Docker

Build the docker image.

docker build -t ink-analyzer .

Run tests from the container.

docker run -it ink-analyzer

NOTE: To run only tests for a single crate, add a -p <crate_name> argument to the docker run command e.g.

docker run -it ink-analyzer -p ink-analyzer-ir

License

Licensed under either MIT or Apache-2.0 license at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Acknowledgements

🌱 Funded by: the Web3 Foundation and Polkadot Treasury.

ink-analyzer's Issues

ink-flipper-analyzer

hey, @davidsemakula I was testing ink-analyzer for simple-flipper ink project but I wonder whether include analysis code inside test module or where? Can you please suggest me where do I add analyer code?

analyzing current source file

// --snip--

#[cfg(test)]
mod tests {
    use ink_analyzer::Analysis;

    #[test]
    fn no_semantic_errors() {
        // read current file as a string literal
        let code = include_str!(file!());

        // run diagnostics
        let diagnostics = Analysis.diagnostics(code);

        // fail test if any diagnostics failed
        assert!(diagnostics.is_empty());
    }
}

hey @davidsemakula I am confused here. In this code file!() macro reads current file as string literal and after that it pass to the diagnostics as a &str. I have checked all the fails condition you have mentioned here in current source file and vscode already warn user before compiling code. Is that because of ink-analyzer = "0.3.0" package which is included in ink project? If so then why do we need to write analyzer test manually? it checks automatically isn't it?. This is just random thought may be this doesn't make sense 😁.
thanks!