## Description
This PR:
- implements partial equivalence in the `core::ops`, as explained in
detail in #6883. The implementation is opt-in and behind the
`partial_eq` experimental feature flag.
- implements `forc migrate` migration steps for automatic migration to
`partial_eq` feature.
- extends the infrastructure for writing `forc migrate` migrations.
- preserves `Annotation`s on `LexedModule`s in the `LexedProgram`.
(Those were before stripped off and not available in the compiled
`Programs`. This resulted in loss off `//!` doc-comments that are
represented as `doc-comment` annotations.)
Extensions in the `forc migrate` infrastructure include:
- possibility to postpone migration steps. This allows writing
multi-step migrations where the first step is usually early adopting an
experimental feature by using `cfg` attributes in code. This possibility
is crucial for migrating our own codebase where we want to early-adopt
and test and stabilize experimental features.
- possibility to match elements on both mutable and immutable parsed
trees. The initial assumption that immutable matching on typed trees
will always be sufficient does not hold. Experimental `cfg` attributes
can remove parts of typed trees that might be needed in analysis.
- `LexedLocate(As)Annotated` for easier location and retrieval of
`Annotated` elements.
- additional implementations of existing traits.
- additional `Modifier`s for modifying existing elements in the lexed
tree.
- `New` struct for convenient creation of often needed lexed tree
elements. Note that we do not expect migrations to generate large new
parts of lexed trees, but mostly to modify or copy and modify existing
ones.
Almost all of the changes in the Sway files are done automatically by
the migration steps. The only manual change was in the `core` library
(`std` library is also automatically migrated) and in slight extension
of two of the tests.
Note that some of the tests have `Eq` traits in trait constraints. As
explained in the #6883, it is not necessary to change those to
`PartialEq`. We might consider changing some of them, for testing
purposes, and such a change is done on one of the tests that was testing
the behavior of the `Eq` trait. But for the majority of the tests, there
is no strict need for switching from `Eq` to `PartialEq`.
Rolling `PartialEq` out in the tests provoked three existing issues that
will be fixed in separate PRs: #6897, #6898, #6899.
## Checklist
- [x] I have linked to any relevant issues.
- [x] I have commented my code, particularly in hard-to-understand
areas.
- [x] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [ ] If my change requires substantial documentation changes, I have
[requested support from the DevRel
team](https://github.com/FuelLabs/devrel-requests/issues/new/choose)
- [x] I have added tests that prove my fix is effective or that my
feature works.
- [ ] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [x] I have done my best to ensure that my PR adheres to [the Fuel Labs
Code Review
Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md).
- [x] I have requested a review from the relevant team or maintainers.
## Description
This PR introduces `forc-migrate`, a Forc tool for migrating Sway
projects to the next breaking change version of Sway.
The tool addresses two points crucial for code updates caused by
breaking changes:
- it informs developers about the breaking changes and **assists in
planing and executing** the migration.
- it **automatically changes source code** where possible, reducing the
manual effort needed for code changes.
Besides adding the `forc-migrate` tool, the PR:
- extends `Diagnostic` to support migration diagnostics aside with
errors and warnings.
- changes `swayfmt` to support generating source code from arbitrary
lexed trees. The change is a minimal one done only in the parts of
`swayfmt` that are executed by migration steps written in this PR.
Adapting `swayfmt` to fully support arbitrary lexed trees will be done
in #6779.
The migration for the `references` feature, migrating `ref mut` to
`&mut`, is developed only partially, to demonstrate the development and
usage of automatic migrations that alter the original source code.
The intended usage of the tool is documented in detail in the "forc
migrate" chapter of The Sway Book: _Forc reference > Plugins >
forc_migrate_. (The generated documentation has issues that are caused
by the documentation generation bug explained in #6792. These issues
will be fixed in a separate PR that will fix it for all the plugins.)
We expect the `forc-migrate` to evolve based on the developer's
feedback. Some of the possible extensions of the tool are:
- adding additional CLI options, e.g., for executing only specific
migration steps, or ignoring them.
- passing parameters to migration steps from the CLI.
- not allowing updates by default, if the repository contains modified
or untracked files.
- migrating workspaces.
- migrating other artifacts, e.g., Forc.toml files or contract IDs.
- migrating between arbitrary versions of Sway.
- migrating SDK code.
- etc.
`forc-migrate` also showed a clear need for better infrastructure for
writing static analyzers and transforming Sway code. The approach used
in the implementation of this PR should be seen as a pragmatic
beginning, based on the reuse of what we currently have. Some future
options are discussed in #6836.
## Demo
### `forc migrate show`
Shows the breaking change features and related migration steps. This
command can be run anywhere and does not require a Sway project.
```
Breaking change features:
- storage_domains (https://github.com/FuelLabs/sway/issues/6701)
- references (https://github.com/FuelLabs/sway/issues/5063)
Migration steps (1 manual and 1 semiautomatic):
storage_domains
[M] Review explicitly defined slot keys in storage declarations (`in` keywords)
references
[S] Replace `ref mut` function parameters with `&mut`
Experimental feature flags:
- for Forc.toml: experimental = { storage_domains = true, references = true }
- for CLI: --experimental storage_domains,references
```
### `forc migrate check`
Performs a dry-run of the migration on a concrete Sway project. It
outputs all the occurrences in code that need to be reviewed or changed,
as well as the migration time effort:
```
info: [storage_domains] Review explicitly defined slot keys in storage declarations (`in` keywords)
--> /home/kebradalaonda/Desktop/M Forc migrate tool/src/main.sw:19:10
|
...
19 | y in b256::zero(): u64 = 0,
| ------------
20 | z: u64 = 0,
21 | a in calculate_slot_address(): u64 = 0,
| ------------------------
22 | b in 0x0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20: u64 = 0,
| ------------------------------------------------------------------
|
= help: If the slot keys used in `in` keywords represent keys generated for `storage` fields
= help: by the Sway compiler, those keys might need to be recalculated.
= help:
= help: The previous formula for calculating storage field keys was: `sha256("storage.<field name>")`.
= help: The new formula is: `sha256((0u8, "storage.<field name>"))`.
= help:
= help: For a detailed migration guide see: https://github.com/FuelLabs/sway/issues/6701
____
Migration effort:
storage_domains
[M] Review explicitly defined slot keys in storage declarations (`in` keywords)
Occurrences: 3 Migration effort (hh::mm): ~00:06
references
[S] Replace `ref mut` function parameters with `&mut`
Occurrences: 0 Migration effort (hh::mm): ~00:00
Total migration effort (hh::mm): ~00:06
```
### `forc migrate run`
Runs the migration steps and guides developers through the migration
process.
## Checklist
- [x] I have linked to any relevant issues.
- [x] I have commented my code, particularly in hard-to-understand
areas.
- [x] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [x] If my change requires substantial documentation changes, I have
[requested support from the DevRel
team](https://github.com/FuelLabs/devrel-requests/issues/new/choose)
- [ ] I have added tests that prove my fix is effective or that my
feature works.
- [ ] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [x] I have done my best to ensure that my PR adheres to [the Fuel Labs
Code Review
Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md).
- [x] I have requested a review from the relevant team or maintainers.
This PR is a WIP that aims to address the first 3 steps in #1833.
This is in anticipation of using `forc test` to support unit testing
(rather than Rust integration testing) #1832.
The `forc test` command remains for now, but outputs a message
explaining that the command is now reserved for unit testing and links
to the issues above.
## TODO
- [x] Create a new `sway-test-rs` repo or similar that can be used as a
`cargo generate` template.
- [x] Update Rust integration testing docs in the Sway book to describe
how to use the `cargo generate` command to easily add Sway integration
testing to an existing Rust project.
## Follow-up
- Create a `forc-test-rs` crate that re-exports and extends `fuels` with
useful `forc` functionality for integration testing (e.g. re-exporting
`forc_pkg::build` to ensure sway code is built and available under
`out/` at the start of testing).
* Copy over changes from PR#1669
* Rework `forc new` in terms of `forc init`
This removes all of the duplicated logic from the `forc new` command in
favour of re-using the `forc init` op.
* Add missing doc
* Add missing comment
Co-authored-by: Rashad Alston <rashad@Rashads-MacBook-Pro.local>
Co-authored-by: mitchmindtree <mitchell.nordine@fuel.sh>
Co-authored-by: Rashad Alston <rashad@Rashads-MBP.attlocal.net>
* forc template resolves the HEAD and fetches the repo. Prints the requested directorie's path
* forc template works with and without template name
* forc init --template removed, pkg.rs unused pub modifier removed
* extra info added before copy, cargo-toml-lint, udeps fix, mdbook fix
* invoke CI
* Update scripts/mdbook-forc-documenter/examples/forc_template.md
Co-authored-by: John Adler <adlerjohn@users.noreply.github.com>
* Update scripts/mdbook-forc-documenter/examples/forc_template.md
Co-authored-by: John Adler <adlerjohn@users.noreply.github.com>
* default url provided, project_name is last parameter to pass without --project_name
* cargo fmt
* println to tracing::info
* local_repo_name to template_name
Co-authored-by: John Adler <adlerjohn@users.noreply.github.com>