Include configurable custom text in reports

[sacha-c]

Is your feature request related to a problem? Please describe.
Users of the application may have specific usage documentation of how to work with sheriff.
To make this documentation available to all receivers of sheriff reports, it would be nice for the slack reports themselves to provide a link to their custom usage documentation.

Describe the solution you'd like
A configurable (markdown?) text which would appear in all reports. Something like:
--report-custom-text, --report-header, --report-subtitle, or --what-else?
This would allow users to add something like:
--report-custom-text Find usage documentation in [cool link](www.google.com)

This also opens the possibility of further report customizations, such as the report title, etc

Describe alternatives you've considered
...

Additional context
...

[scastlara]

Related: do all options available in the config file need to be exposed in the cli?

These options you've described seem best suited for a config file.

(For reference, cli apps such as ruff only expose a subset of options as cli flags)

[scastlara]

Some random ideas:

• The report itself could have an optional header/summary.
• Each vuln section could have an optional header/summary.

One possibility:

[report.issue.text_replacements]
main_header = "> this md will appear just below the issue title"
sections = {
   acknowledged = "> this will only appear in the ack section"
}

[sacha-c]

Related: do all options available in the config file need to be exposed in the cli?

These options you've described seem best suited for a config file.

(For reference, cli apps such as ruff only expose a subset of options as cli flags)

Yeah maybe not!

I was using renovate as a reference: https://docs.renovatebot.com/configuration-options/#branchprefix
They mostly have everything (or at least, a lot) configurable as cli options & by config

But, if we decide to have a config file kind of specific for some options, I think it could also be a good idea
In that case maybe we could think of parsing the config file ourselves using https://github.com/pelletier/go-toml, rather than go-cli. This way we can support more TOML syntax such as dictionaries, etc...

[scastlara]

I am totally neutral on both approaches! Both have their strengths (parity/symmetry vs less cli surface).

Just wanted to bring up the possibility.

[sacha-c]

I am totally neutral on both approaches! Both have their strengths (parity/symmetry vs less cli surface).

Just wanted to bring up the possibility.

Yep!

I think I tend to like the idea of separating file configuration from the CLI. This way we can really configure it using TOML to the fullest.
And its not incompatible with keeping configuration parity if we want

This would mean changing the configuration interface again

report-to-slack-channel = ""
report-to-email = ""

could finally become

[report.to]
email = ""
slack-channel = ""

[report.issue.text_replacements] # or similar
main_header = "> this md will appear just below the issue title"
sections = {
   acknowledged = "> this will only appear in the ack section"
}

We can discuss this in a separate story dedicated to the CLI config file though #32

[scastlara]

I assigned myself to this but realistically I won't make it soon enough! I am freeing it!