ink! analyzer (phase 2) - milestone 1

[davidsemakula]

Milestone Delivery Checklist

• The milestone-delivery-template.md has been copied and updated.
• The invoice form 📝 has been filled out for this milestone.
• This pull request is being made by the same account as the accepted application.
• I have disclosed any and all sources of reused code in the submitted repositories and have done my due diligence to meet its license requirements.
• In case of acceptance, the payment will be transferred to the BTC/ETH/fiat account provided in the application.
• The delivery is according to the Guidelines for Milestone Deliverables.

Link to the application pull request: w3f/Grants-Program#1904 < please fill this in with the PR number of your application.

[dsm-w3f]

@davidsemakula thank you for the milestone delivery. Please see the evaluation document and provide the proper answers and fixes. Let me know when I can continue this evaluation.

[davidsemakula]

@dsm-w3f Thanks for swift review and feedback.

I ran cargo clippy and received some warnings:

The clippy warnings should be fixed, you'll need to pull the latest changes from master.

As a side note, I'm curious if you ran cargo +nightly clippy or passed any extra flags to get them, because the CI checks didn't catch them 🙂

I would like to test using the VS Code Extension. Could you provide a guide with usage examples that show these deliverables?

For manual testing in VS Code, 1 and 2 are fully testable, but 4 is only partially testable in VS Code, so I will provide some examples for those.
However, 3 isn't testable at all via VS Code at the moment - technically (in terms of the milestones schedule), these features will fully land in VS Code in milestone 7.

Below is a testing guide for manual testing with VS Code:

Setup

Option 1: Marketplace Install

• Install the VS Code extension directly from the VS Code marketplace following this guide
• Clone the VS Code extension repo and open the test-fixtures directory in VS Code.

Option 2: Debug Environment

• Follow the VS Code extension's "Development and Testing Guide" to set up a test environment.
• Use the "Run Extension (without Rust Analyzer)" launch configuration to test the extension in an isolated environment (see further instructions in the "Development and Testing Guide").

NOTE: If you're using the Debug Environment option and have already cloned the VS Code extension repository in the past, be sure to pull the latest changes, and (if it exists) delete the /server directory (this will be automated in a future milestone) to make sure you get the latest release of the language server.

Testing

The instructions below are written for the flipper contract in the "test-fixtures" directory/workspace of the VS Code extension's repository, so open that in VS Code first.

1. Quickfixes for diagnostic errors and warnings.

Action:

Remove the ink! storage item i.e.

#[ink(storage)]
pub struct Flipper {
    value: bool,
}

Expected Result:

• You should see diagnostic squiggles on the ink! contract mod item (i.e. covering the line pub mod flipper {).
• Hovering over the squiggles should show a diagnostic message like Missing ink! storage.
• Hovering over the squiggles should reveal a "quickfix" to Add ink! storage "struct".
• Alternatively, positioning the cursor on the squiggles and clicking the "light bulb" that's trigger by this action will also reveal the above quickfix.

Additional testing examples:

• Remove other required ink! entities (e.g. remove all ink! messages).
• Add a conflicting argument to one of the ink! attributes (e.g. change #[ink(constructor)] to #[ink(constructor, topic)] or change #[ink::contract] to #[ink::contract(payable)]).
• Add an unknown argument to one of the ink! attributes (e.g. change #[ink(constructor)] to #[ink(constructor, xyz)]).
• Apply an ink! attribute to the wrong Rust item kind (e.g. add an #[ink::test] attribute above the line impl Flipper {).
• Add unexpected or remove required Rust item invariants e.g. remove the Self return type (i.e. remove -> Self) from one of the ink! constructor functions or add a self reference receiver (i.e. add &self as the first parameter) to one of the ink! constructor functions.
• Add clashing selectors to ink! constructors or ink! messages (e.g. change all #[ink(message)] attributes to #[ink(message, selector = 1)], or add an ink! constructor or ink! message with the same fn name as an existing callable e.g. add another ink! message name flip).
• Move an ink! entity to the wrong scope (e.g. move an ink! message into the root of the contract mod - e.g. move the flip ink! message to the line right after the ink! storage struct).

All the above edits should result in diagnostics squiggles that reveal one or more quickfixes for the issues.
NOTE: The list of diagnostics and quickfixes above is not exhaustive.

2. ink! e2e test attribute macro support

Diagnostics and quickfixes:

Perform any of the actions below to get ink! e2e macro related diagnostics and quickfixes:

• Add a conflicting argument to an ink! e2e test attribute (e.g. change #[ink_e2e::test] to #[ink_e2e::test(payable)]).
• Add an unknown argument to an ink! e2e test attribute (e.g. change #[ink_e2e::test] to #[ink_e2e::test(xyz)]).
• Apply an ink! e2e test attribute to the wrong Rust item type (e.g. add an #[ink_e2e::test] attribute above the line impl Flipper {).

All the above edits should result in diagnostics squiggles that reveal a few quickfixes for the issues.

Completions:

• For macro completions, make one of the ink! e2e test attributes "incomplete" (e.g. change #[ink_e2e::test] to #[ink_e] or #[ink_e2e::t]) and either start typing to complete the macro name or hit Cmd/Ctrl + Space to trigger a completion proposal manually.
• For complementary argument completions (i.e. additional_contracts, environment and keep_attr), change #[ink_e2e::test] to #[ink_e2e::test()], and either typing the ( character, or starting to type inside the brackets, or hitting Cmd/Ctrl + Space should trigger completion proposals.

Code/intent actions:

• Positioning the cursor either on an ink! e2e test attribute (e.g. on any #[ink_e2e::test]) or on the fn item "declaration" (e.g. anywhere on the line async fn it_works(mut client: ink_e2e::Client<C, E>) -> E2EResult<()> { but not inside the body) will trigger a "light bulb" with code actions for adding complementary arguments to the ink! e2e test attribute (i.e. additional_contracts, environment and keep_attr).
• Positioning the cursor on an fn item without any other ink! attributes will trigger a "light bulb" with the option to Add an ink! e2e test attribute to the fn item.

Hover content:

Hovering over an ink! e2e test attribute will reveal related usage documentation in a popup.

3. Creating a new ink! project with a contract stub

Not currently implemented in VS Code, only available in the semantic analyzer.

NOTE: The equivalent VS Code feature is scheduled for milestone 7.

4. Code/intent actions for inserting code stubs/snippets for relevant ink! entities

As mentioned above, this feature has limited VS Code support at the moment, with the main limitation being that by default VS Code only requests code actions when the cursor is focused on an item, not whitespace.
So "root-level" entity actions (e.g. adding ink! entities at the root of the file i.e. in whitespace) will not be triggered at the moment (even if the semantic analyzer already supports this feature).

However, the example code actions below (which are triggered by positioning the cursor on an item) already work in the VS Code extension:

• Positioning the cursor on the ink! contract mod item "declaration" (i.e. on the line pub mod flipper {) will trigger a "light bulb" with code actions for adding an ink! event "struct", ink! message "fn" or ink! constructor "fn" to the ink! contract.
• After inserting an ink! event (e.g. use code action described above), positioning the cursor on the ink! event struct item "declaration" (i.e. on the line pub struct MyFlipperEvent {) will trigger a "light bulb" with code actions for adding an ink! topic "field".
• Positioning the cursor on the item "declaration" of a "test" mod (i.e. a mod annotated with #[cfg(test)] or similar e.g. on the line mod tests {) will trigger a "light bulb" with code actions for adding an ink! test "fn" to the mod item.
• Positioning the cursor on the item "declaration" of a "test" mod with an additional e2e-tests feature condition (i.e. a mod annotated with #[cfg(all(test, feature = "e2e-tests"))] or similar e.g. on the line mod e2e_tests {) will trigger a "light bulb" with code actions for adding an ink! e2e test "fn" to the mod item.

NOTE: Full VS Code support for this feature is scheduled for milestone 7.

Finally, I'll refactor this into a more generic feature testing guide for the VS Code extension at some point in the future, but for now I'll leave it as a comment here as it's a bit too specific to this milestone for me right now.

[dsm-w3f]

@davidsemakula thank you for the answer. I checked again and the application is working fine in vscode. See details in the evaluation document. The milestone is accepted. I'll forward your invoice internally and the payment should take place within two weeks. Great job!

[github-actions]

Congratulations on completing the first milestone of this grant! As part of the Grants Program, we want to help grant recipients acknowledge their grants publicly. To that end, we’ve created a badge for projects that successfully deliver their first milestone. Please use the badge only in reference to the work that has been completed as part of this grant, so please do not display it on your team or project's homepage unless accompanied by a short description of the grant. Furthermore, you're now welcome to announce the grant publicly. Please remember to observe the foundation’s guidelines in doing so. If you haven't already, reach out to grantsPR@web3.foundation for feedback on your announcement and cross-promotion.

Thank you for your contribution, and good luck! If you have any remaining milestone, let us know if you encounter any delays by leaving a comment on the application PR or submitting an amendment.