"bump overlay" should log a warning when JSONPath doesn't match anything

[hkosova]

When writing JSONPath expressions, it's common to make mistakes where the expression is syntactically valid but matches nothing. Currently bump overlay just silently ignores such targets, which complicates troubleshooting.

It would be nice if the tool could warn the user about such noop targets. These warnings could be either always on, or enabled by some flag. For example speakeasy overlay apply has the --strict flag for this purpose.

Some common errors:

1. Typos in node names, values, filters:

   $..parameters[?( @.name == 'fron_date' )]
   
   $..paramaters[?( @.name == 'from_date' )]
   
   $.servers[?( @.desciption == 'Dev' )]
   

2. Skipping nodes in a path:

   - target: $.components.schemas.SchemaName.propName   # should be: ...SchemaName.properties.propName
     update:
       description: something
       example: 123

3. Extra nodes in a path:

   $.paths.*[?( @.operationId == 'get_foo' )].get   # '.get' is not needed here

4. Consider an overlay that targets an endpoint by its path or operationId:

   $.paths['/foos/{id}'].get
   
   $.paths.*[?( @.operationId == 'get_foo' )]

   Later this endpoint gets renamed (e.g. /foos/{id} becomes /foos/{foo_id}) or its operationId gets changed (e.g. maybe op IDs are autogenerated and the algorithm changes).

As an overlay author and maintainer, I would like to get notified about non-matches so that I can update the overlay to match the current state of my API.

[samanthawritescode]

Big +1 to this. I'm starting to write and maintain overlays for my spec and I'm worried about updates to my API unknowingly affecting how my overlays work. I would like to know so I can update the overlays.

[grossyoan]

Thanks for your feedback, it fully makes sense.

We're talking about it internally to see how it could be added to our roadmap.

[grossyoan]

Hi,

This feature is now available in the last version of the CLI. Thanks again for your feedback 🙏

Have a great day,
Yoan

[samanthawritescode]

@grossyoan thank you for adding this! Would it be possible to force the bump overlay command to fail with a non-zero exit code if one of the "no matching elements" warnings exists? Perhaps with a --strict flag?

I don't have faith that all engineers at my company will heed the warnings without an explicitly failing command 😅

[grossyoan]

Hi @samanthawritescode,

Thanks for your feedback.

We don't usually fail an action unless there's something "fatal" to it, we prefer to output warnings, like we do during deployment.

However, I totally get your use case. We'll talk about it internally to see if we offer a --strict option in the future.

Have a nice day,
Yoan