[pkg/ottl] Add parser utility to rewrite statements appending missing paths context

[edmocosta]

Description

This PR is part of #29017, and adds the ottl.Parser[K].AppendStatementPathsContext function, allowing components to rewrite statements appending missing ottl.path context names.

For examples, the following context-less statement:

set(value, 1) where name == attributes["foo.name"]

Would be rewritten using the span context as:

set(span.value, 1) where span.name == span.attributes["foo.name"]

Why do we need to rewrite statements?

This utility will be used during the transition from structured OTTL statements to flat statements.
Components such as the transformprocessor will leverage it to support both configuration styles, without forcing
users to adapt/rewrite their existing config files.

Once the component turns on the ottl.Parser[K] path's context validation, new configuration style usages will be validated, requiring all paths to have a context prefix, and old configuration styles will automatically rewrite the statements using this function.

For more details, please have a look at the complete draft implementation.

Link to tracking issue

#29017

Testing

Unit tests

Documentation

No changes

[edmocosta]

I've moved the AppendStatementPathsContext into the parser.go file as @TylerHelmuth suggested.
Do you folks have any thoughts on this #35716 (comment)? Thank you!

[edmocosta]

@TylerHelmuth @evan-bradley, I've addressed Evan's suggestions at 8225cec
In addition to that, I've include two safe guards, one for invalid offsets so it won't panic if somehow invalid values are passed on, and another to ensure the offsets are sorted, otherwise the function wouldn't work.

It should not receive invalid offsets, but considering those values are coming from the grammar lib, I think it's ok to handle them and provide an error message instead of panicking.

Currently, the offsets values are sorted, but that assumes that the grammar visitor will never change the order it collects the paths, which IMO, is not a commitment we should make.

Please let me know if you prefer to not add those conditions. Thanks!

[evan-bradley]

It's probably not strictly necessary to add checks since this is an internal function, but the checks are easy and I think it's good to be cautious. Thanks for thinking ahead!