Desire for 'calculated' fields

[richardbarlow]

We use strictdoc to manage our risk assessments. As part of the risk assessment process it is necessary to score each risk based on severity and likelihood. From those two numeric values a single 'risk score' is calculated. In our case the risk score is determined from a look-up table based on the severity and likelihood (so not a simple mathematical function). At the moment we have to manually update the risk score whenever the severity or likelihood is modified, which is a laborious and error-prone process. We could (and will) implement a CI check that the manually recorded risk-score is correct, but we would prefer it if we didn't have to perform any manual work at all.

I know that this is potentially quite a deviation from the current architecture of strictdoc, but we would find it incredibly helpful if there was the ability to have 'calculated' fields, whose value is determined by a small python function based on the value of other fields. Ideally the result of the calculation would be visible in all 'presentation' forms (live server, exported format, python API).

[stanislaw]

Hi @richardbarlow

This is very interesting and is something that I would like to implement myself for a different reason (making requirements connect to each other's data using Python) but there was no good time spent on conceptualizing this.

Before we discuss this non-trivial feature: previously, you asked about using the API here: #1378. To simplify your existing workflow, you could simply implement a Python script, learning from the existing commands of StrictDoc (see https://github.com/strictdoc-project/strictdoc/blob/main/strictdoc/commands/manage_autouid_command.py). You would give your script an SDoc file, a script would populate all dynamic fields based on the formula of your choice, and then it would give you an updated SDoc file back. Could this improve the situation a little?

Regarding the calculated fields: I am imagining that the GRAMMAR/ELEMENT/FIELDS grammar could be extended with a field such as DYNAMIC: or CALCULATED:?, and it would simply point to a Python file that modifies the requirement. I don't think we want to write Python directly in SDoc? 🤔 Inside a Python file, it would be possible to access things like the current node, its document, its grammar, the traceability index, etc.

It would be great to make this feature's concept elegant/consistent. I am open to suggestions.

[richardbarlow]

Excellent!

To simplify your existing workflow, you could simply implement a Python script, learning from the existing commands of StrictDoc (see https://github.com/strictdoc-project/strictdoc/blob/main/strictdoc/commands/manage_autouid_command.py). You would give your script an SDoc file, a script would populate all dynamic fields based on the formula of your choice, and then it would give you an updated SDoc file back. Could this improve the situation a little?

Hmm yes, that is a good point. It would be a step towards a better solution. It's not ideal as it would require someone to run the script to update the scores (I wouldn't want our CI job to be modifying and committing to the repo automatically), but as long as a CI check detects invalid scores we will be safe. Also, updating them in this way makes it quick and easy to do.

Before we discuss this non-trivial feature ... Regarding the calculated fields: I am imagining that the GRAMMAR/ELEMENT/FIELDS grammar could be extended with a field such as DYNAMIC: or CALCULATED:?, and it would simply point to a Python file that modifies the requirement. I don't think we want to write Python directly in SDoc? 🤔 Inside a Python file, it would be possible to access things like the current node, its document, its grammar, the traceability index, etc.

I agree that this is a non-trivial feature and therefore requires some careful thought and design.

I think that 'dynamic' is probably a better term for this feature.

Things that I can think of off the top of my head that should be considered are:

• What environment does the python code execute in? Currently we install and execute strictdoc in a virtualenv, so in our use case we would be able to install whatever is necessary in the same virtualenv and strictdoc would be able to execute it
• How does strictdoc locate the python file(s)? I would suggest that strictdoc should import a module as specified by the user (e.g. in the sdoc file the user defines the python module to import. That way we can leverage the usual python module resolution mechanism.
• How does strictdoc know what to run?. If the user-specified module is imported then for each dynamic field a python function can be specified that has the required signature. Perhaps this and the above point could be solved using the same approach as setuptools entry points (https://setuptools.pypa.io/en/latest/userguide/entry_point.html) where the module and function are specified separated by a colon?
• What context does the python function require?. As a bare minimum the current note, but some additional context would probably be sensible. As you said, the document and traceability index would be sensible too.
• How does the python function mutate the state?. Does it modify the current node object passed to it? If so, how is it prevented from unintentionally modifying other fields? Perhaps it should just return the value to be used for the particular dynamic field that it is populating?
• Is there a need for more complex functions that can modify/output more than one dynamic field at a time? I.e. a single python function that outputs the value for two dynamic fields
• How can dynamic fields use the values from other dynamic fields?. This one is a massive can of worms. The grammar or the function itself would need to define its dependencies and strictdoc would need to perform dependency resolution.
• Should there be a way for a function to maintain context/state across invocations?. This may not be particularly valuable if the execution order is undefined. However, there may be use cases where it is helpful to retain some state from previous invocations. This could be implemented by having strictdoc instantiate a user class for each sdoc file and then calling a method on it - this could be the interface rather than just a free function? If so, perhaps the class can somehow indicate if it should be per-node, per-sdoc or per-strictdoc-invocation scoped (e.g. instantiate once per node, once per sdoc, once per strictdoc run) - a bit like pytest fixture scoping.