RFC - Better Bolt/Puppet plan detection

[glennsarti]

Problem

Bolt/Puppet plan files (*.pp manifest files) are raising linting/parsing errors. This is due to Pupet Editor Services (PES) not detecting it is a plan file and then not setting the Puppet parser into "tasks" mode.

Note that we can't force all puppet manifests into "tasks" mode as there are things you can't do in plans but you can in normal manifests and vice versa.

This RFC will describe how PES can reliably detect whether manifests are a plan or not.

Current Detection

The current detection is based on the documenation at https://puppet.com/docs/bolt/latest/writing_plans.html#concept-4485

• Plans must be in a module, in the /plans directory
• Modules must contain a metadata.json file

This is codified at https://github.com/lingua-pupuli/puppet-editor-services/blob/78bb4b108ed70b72ae48c08b56232579af36b92b/lib/puppet-languageserver/document_store.rb#L57-L64

Why the current detection fails

Bolt has introduced the concept of a Bolt project dir (or Boltdir) and this has caused issues like #127 and #128

https://puppet.com/docs/bolt/latest/bolt_project_directories.html

So now there are two aditional scenarios where plans can be located:

Note that in neither of these directory trees are a metadata.json or environment.conf so PES thinks that these .pp files are "standalone" and there is no workspace metadata information, therefore the linting is never put into "tasks" mode.

Local project directory

project/
├── Puppetfile
├── bolt.yaml
├── data
│   └── common.yaml
├── inventory.yaml
└── site-modules
    └── project
        ├── manifests
        │   └── my_class.pp
        ├── plans
        │   └── diagnose.pp  <---- THIS IS A PLAN
        └── tasks
            ├── init.json
            └── init.py

Embedded project directory

project/
├── Boltdir
│   ├── Puppetfile
│   ├── bolt.yaml
│   ├── data
│   │   └── common.yaml
│   ├── inventory.yaml
│   └── site-modules
│       └── project
│           ├── manifests
│           │   └── my_class.pp
│           ├── plans
│           │   └── diagnose.pp  <---- THIS IS A PLAN
│           └── tasks
│               ├── init.json
│               └── init.py
├── src #non Bolt source code for the project
└── tests #non Bolt tests for the project

Also note that plans can exist in subdirectories, for example project/Boltdir/site-modules/project/plans/foo/bar/wizz/diagnose.pp is a plan called project::foo::bar::wiz::diagnose

[glennsarti]

Plan Detection Solution 1

While naive, this will be effective.

"Given the full path to the .pp file, if it contains a directory called plans, AND that plans is not a sub-directory of manifests, then it is a plan file"

/project/Boltdir/site-modules/project/plans/foo/bar/wizz/diagnose.pp is a plan

something/plans/foo/bar/wizz/diagnose.pp is a plan

project/Boltdir/site-modules/project/manifests/init.pp is not a plan

project/Boltdir/site-modules/project/manifests/plans/init.pp is not a plan

Edit 1 : Updated with @genebean 's comments

[glennsarti]

For ref, this is how Bolt does it's directory detection https://github.com/puppetlabs/bolt/blob/75a838a99cd24cfe9194a97923f162781685a4ae/lib/bolt/boltdir.rb#L5-L51

[genebean]

Will that cause problems in a scenario where I have something like profile::app_name::plans::plan1 which would be located at profile/manifests/app_name/plans/plan1.pp?

Maybe there should be a conditional added to the "if path includes /plans" so that its actually "if path includes /plans and /plans is not a subfolder of /manifests"

[glennsarti]

Will that cause problems in a scenario where I have something like profile::app_name::plans::plan1 which would be located at profile/manifests/app_name/plans/plan1.pp?

Yup - thus the While naive comment.

Maybe there should be a conditional added to the "if path includes /plans" so that its actually "if path includes /plans and /plans is not a subfolder of /manifests"

👍

[glennsarti]

Closing and going with

---

"Given the full path to the .pp file, if it contains a directory called plans, AND that plans is not a sub-directory of manifests, then it is a plan file"

/project/Boltdir/site-modules/project/plans/foo/bar/wizz/diagnose.pp is a plan

something/plans/foo/bar/wizz/diagnose.pp is a plan

project/Boltdir/site-modules/project/manifests/init.pp is not a plan

project/Boltdir/site-modules/project/manifests/plans/init.pp is not a plan