Bug: Comments interpreted in policy documentation generation

[artis3n]

Bug: Comments interpreted in policy documentation generation

[artis3n]

Git diff shows this fixing the issue! Comments are removed from the generated documentation

[jalseth]

Konstraint treats the @kinds tag as the end of the header block when parsing the policy description. This was selected when @kinds was the only tag Konstraint supported, so this may need a refresh.

Since all of the @ tags are optional and can exist in any order, it may be best to add an @end tag or something similar so Konstraint can easily know when a comment is no longer a part of the header block. What are your thoughts @artis3n @jpreese ?

[artis3n]

Ah, and I don't use the @kind tag because I'm writing policies beyond just kubernetes - using Konstraint for policy documentation of the rest of what Conftest can test as well as k8s.

I understand Konstraint is primarily a tool to templatize policies between Conftest and Gatekeeper, but to leverage its policy self-documentation utilities - I would prefer Konstraint to use the contiguous block of comments above a package declaration / at the top of a file and ignore any other comments in the file. Then, the content can exist in that contiguous block in any order, and anything within that contiguous comment block that does not begin with @ should be treated as part of the policy description.

read lines in file, while line begins with #, treat as part of policy header, break when line no longer begins with #. But it doesn't look like you maintain the file structure when parsing the Rego, you have all comments in the file and have to work with that. If that is the case, then adding a @end works. That suggests there should be a @begin or @start highlighting the start of where Konstraint should look for policy declaration - if the r.comments is ordered such that the comment lines appear in the same order that they are written in the file, earlier lines first.

I have used Go, many years ago, and have only interacted with rego for writing policies. So hopefully my comments make sense for the tools we have in the language.

[jalseth]

That sounds good, and it shouldn't be too hard to implement. I'll probably have time to get to this next week.

[jalseth]

@artis3n this was implemented in #104 and it seems to work in my testing. Can you try with your policies and let me know if you run into any issues?

[artis3n]

Will check on Monday

[artis3n]

Is there any particular cadence to Konstraint's release cycle? It would be nice to take advantage of this fix but I don't see that #104 has been released.

[jalseth]

@artis3n We don't have any formal release schedule at the moment, but I think it would be fair to target monthly at a minimum going forward, with a release every 2 weeks being a stretch goal. @jpreese do you have any thoughts?