Cfn Lsp Extra

An experimental cloudformation language server (with support for SAM templates) built on top of cfn-lint and the Cloudformation user guide, aiming to provide hovering, completion, etc. YAML and JSON are supported, though YAML has more features currently implemented (for example snippets) and will give a better experience. Trust me.

cfn-lsp-extra-demo.mp4

Features

Method	Status
textDocument/hover	Done for resources (in particular, required properties for a resource will be auto-expanded), resource properties, subproperties, !Refs and intrinsic functions.
textDocument/completion	Done for resources, resource properties, subproperties, property values (for enums), refs, !GetAtts and intrinsic functions. TODO Fn::GetAtt.
textDocument/definition	Done for !Refs and !GetAtts. TODO mappings.
textDocument/publishDiagnostics	Done through cfnlint.

Also checkout the changelog.

Installation

First install the executable, pipx is recommended, but you can use pip instead if you like to live dangerously:

pipx install cfn-lsp-extra

Or get the bleeding edge from source:

pipx install git+https://github.com/laurencewarne/cfn-lsp-extra.git@$(git ls-remote [email protected]:laurencewarne/cfn-lsp-extra.git | head -1 | cut -f1)

Updating:

pipx upgrade cfn-lsp-extra

Keeping cfnlint Up to Date

Updates to cfn-lsp-extra typically lag behind cfnlint which it uses for diagnostics, which can become an irritation when it leads diagnostics from cfn-lsp-extra becoming outdated and new desirable lint rules not showing. Assuming you installed cfnlint using pipx, you can use:

alias cfn-lsp-extra='env PYTHONPATH=$HOME/.local/pipx/venvs/cfn-lint/lib/python<PYTHON_VERSION>/site-packages/ cfn-lsp-extra'

To ensure cfn-lsp-extra uses your system cfnlint version. Note This comes with some risk with respect to clashing dependencies, but I would expect it to generally work as long as cfnlint and cfn-lsp-extra aren't wildly out of date.

Emacs

Install the lsp-cfn.el package.

Neovim

Make sure you're running at least 0.8, then add the following in ~/.config/nvim/filetype.lua:

vim.filetype.add {
  pattern = {
    ['.*'] = {
      priority = math.huge,
      function(path, bufnr)
        local line1 = vim.filetype.getlines(bufnr, 1)
        local line2 = vim.filetype.getlines(bufnr, 2)
        if vim.filetype.matchregex(line1, [[^AWSTemplateFormatVersion]] ) or
           vim.filetype.matchregex(line1, [[AWS::Serverless-2016-10-31]] ) then
          return 'yaml.cloudformation'
        elseif vim.filetype.matchregex(line1, [[["']AWSTemplateFormatVersion]] ) or
           vim.filetype.matchregex(line2, [[["']AWSTemplateFormatVersion]] ) or
           vim.filetype.matchregex(line1, [[AWS::Serverless-2016-10-31]] ) or
           vim.filetype.matchregex(line2, [[AWS::Serverless-2016-10-31]] ) then
          return 'json.cloudformation'
        end
      end,
    },
  },
}

Then you can use one of:

1. Neovim's built-in LSP client:

require('lspconfig.configs').cfn_lsp = {
  default_config = {
    cmd = { os.getenv("HOME") .. '/.local/bin/cfn-lsp-extra' },
    filetypes = { 'yaml.cloudformation', 'json.cloudformation' },
    root_dir = function(fname)
      return require('lspconfig').util.find_git_ancestor(fname) or vim.fn.getcwd()
    end,
    settings = {
      documentFormatting = false,
    },
  },
}
require('lspconfig').cfn_lsp.setup{}

2. LanguageClient-neovim:

let g:LanguageClient_serverCommands = {
    \ 'yaml.cloudformation': ['~/.local/bin/cfn-lsp-extra'],
    \ 'json.cloudformation': ['~/.local/bin/cfn-lsp-extra']
    \ }

Patches documenting integration for other editors are very welcome!

Development

cfn-lsp-extra uses nox for virtualenv management and poetry for dependency management. You can install both of them using:

pipx install nox
pipx install poetry

And then run tests, linting, etc (switching 3.9 for whichever Python version):

nox --session tests-3.9              # unit tests
nox --session integration-tests-3.9  # integration tests
nox --session lint-3.9               # flake8 lints
nox --session mypy-3.9               # mypy checks

Alternatives

vscode-cfn-lint

cfn-lint

Note this is used by cfn-lsp-extra under the hood to generate diagnostics. One difference with cfn-lsp-extra is that diagnostics will be refreshed every time you make a change to the document, in other words you don't need to save the file.

yamlls

You can use yamlls in conjunction with the Cloudformation schema at https://www.schemastore.org/json/ as an alternative. For Emacs, lsp-mode can install yamlls for you, from there you could do something like:

(defun my-yamlls-cloudformation-setup ()
  ;; There's also one for serverless
  (lsp-yaml-set-buffer-schema "https://raw.githubusercontent.com/awslabs/goformation/master/schema/cloudformation.schema.json")
  (setq-local
   lsp-yaml-custom-tags
   ["!And"
    "!Base64"
    "!Cidr"
    "!Equals"
    "!FindInMap sequence"
    "!GetAZs"
    "!GetAtt"
    "!If"
    "!ImportValue"
    "!Join sequence"
    "!Not"
    "!Or"
    "!Ref Scalar"
    "!Ref"
    "!Select"
    "!Split"
    "!Sub"
    "!fn"]))

;; Using the mode defined by https://www.emacswiki.org/emacs/CfnLint
(add-hook 'cfn-yaml-mode-hook #'my-yamlls-cloudformation-setup)
(add-hook 'cfn-yaml-mode-hook #'lsp-deferred)

This will give you completions (and some support for value completions?), though no hover documentation.