Refactorings
How a refactoring is built, and the rules every refactoring follows
The refactorings built so far are described for users on VS Code extension. This page says how a refactoring is built, and the rules every refactoring follows. The planned ones are on Refactorings in Work in progress.
How a refactoring is built
- In the compiler, not the server. A refactoring is a function in the compiler’s
Refactorings/folder, one file each, in the namespaceNyxCompiler.Refactorings, from a checked module (or the parser’s syntax tree, for one that needs no types) and a position or selection to a list ofTextEdits, as a diagnostic’sFixalready is (Diagnostics.Fix).Refactoring.fsholds what they share, and itsRefactoringTextmodule what the ones that write code share. The language server’sCodeActionHandleronly lists what’s available at the selection, a refused one disabled with its reason. So every refactoring is tested in F#, inFeatures/Refactorings/of the compiler’s tests, without an editor, and could be offered from the CLI too. - It never changes what the program means. Each refactoring states when it’s refused, and refuses with a reason rather than producing code that type-checks differently: a name that would be shadowed, a cell assigned in between, a workflow keyword whose meaning depends on its block. Where it can’t tell from the syntax, it compiles its result and refuses if there are new errors or a name refers to something else. Its tests include the refusals.
- Compiling waits until it is picked. A refactoring that compiles its result offers it as Offer.Deferred: its title and kind, and a function that compiles and gives the Available or Refused offer. Editors ask for code actions on every move of the cursor, so CodeActionHandler lists a deferred one without its edits and decides it in codeAction/resolve, when the user picks it: a request compiles nothing. Refused then, its reason is shown as a message rather than in the menu. A client that can’t resolve an action’s edits gets them decided in the request. The formatter’s settings are read once per text of the document (OpenDocument.RefactoringOptions). Tests decide every offer with Offer.decided.
- Its output is formatted. Edits are laid out as the formatter would lay out the result
(
RangeFormatting.formatRange), so applying a refactoring never leaves codenanyx formatwould change. - Code action kinds are the standard ones, so editors put them in the usual menus:
refactor.extract(introduce local, introduce function and introduce type alias),refactor.inline(inline a def or a type alias),refactor.rewrite(write the inferred type, write the types of the_s, call and pipe, shorthand lambdas, match andif, concatenation and interpolation, implement a context, make a type protected or private), andsource.organizeImports. Rename and selection ranges have their own LSP requests. - A new name starts a rename. A refactoring that invents a name (introduce local, introduce function, introduce type alias, a shorthand lambda’s parameters) carries the
command
nanyx.renameAt, which the VS Code extension registers: after the edits, it puts the cursor on the name and starts a rename. - Edits in other files are TextEdits whose span names the file. A refactoring that changes the files of the package, as making an exported type protected or private does, takes them compiled when it is decided (DocumentStore.CompilePackage) and a function that compiles the package again with new texts (DocumentStore.RecompilePackage, which rename uses too), and CodeActionHandler places each file’s edits in its text, the editor’s if it is open.