Feat/add syntax autogeneration

[Benni0]

PR Type

What kind of change does this PR introduce?

• Feature
• Bug Fix
• Refactoring (no functional or API changes)
• Documentation Update
• Maintenance (dependency updates, CI, etc.)

Summary

Adds support for custom command syntax auto generation based on command name and parameter definition. If syntax parameter is not provided, the syntax will be generated. The value syntax for each parameter is either derived from the validation type or can be defined by the syntax attribute of the parameter. It's also possible to omit a parameter from the syntax using the syntaxGeneration attribute.

Changes

Added the attributes syntax and syntaxGeneration to the attribute object, and made the syntax attribute on the custom command object optional. Additionally removed the length limit from custom commands syntax attribute, because it might be to low for many use-cases.
Implemented automatic syntax generation and also formatting with line breaks on a soft limit of 150 characters by line in searchbnf.conf.

This is another update after #1977 and #1979.

User experience

Now the user get's automatically a syntax which includes all command parameters and basic value definition. After this change, the developer must only define parameters, where the automatic generated syntax is not sufficient. It is still possible to override the automatic generation by specifying the syntax attribute, so nothing changes for existing projects.

Gerneral notes for syntax in searchbnf.conf:

• The search assistant works well if the value syntax is a predefined type like <bool>, <int> or <string>.
• The search assistant have a weird behavior, if the value syntax is a list of static options, like (high|medium|low), as it shows only the value options, not the parameter.
• The list syntax is not shown in auto completion in the search assistant but it might be helpful as it is listed in the full syntax.
• Escaped quotes in searchbnf.conf seem not to work as documented, as they are not sown anywhere in the search assistant.

The current implementation is based on my experience, which syntax definitions works best for the given scenarios. I'm still not sure if option lists are a good solution, but they are used in many splunk core implementations, so the generator are also using them.

Checklist

If an item doesn't apply to your changes, leave it unchecked.

Review

• self-review - I have performed a self-review of this change according to the development guidelines
• Changes are documented. The documentation is understandable, examples work (more info)
• PR title and description follows the contributing principles
• meeting - I have scheduled a meeting or recorded a demo to explain these changes (if there is a video, put a link below and in the ticket)

Tests

See the testing doc.

• Unit - tests have been added/modified to cover the changes
• Smoke - tests have been added/modified to cover the changes
• UI - tests have been added/modified to cover the changes
• coverage - I have checked the code coverage of my changes (see more)

Demo/meeting:

Reviewers are encouraged to request meetings or demos if any part of the change is unclear

[kkedziak-splunk]

Review Summary

This PR adds automatic syntax generation for custom search commands based on argument definitions. This is a nice quality-of-life improvement that reduces the need for users to manually specify syntax strings.

Issues found:

1. Chain of if statements instead of elif (create_searchbnf_conf.py): The validator-type matching logic uses a series of independent if statements instead of elif. This means every condition is checked even after a match. For example, if validator == "Integer", the first if matches, but then validator == "Boolean", validator == "Set", etc. are all still evaluated. Worse, the param_syntax variable could be overwritten if a validator name accidentally matched multiple conditions. Should use elif for correctness and performance.

2. Float mapped to <int> in syntax (create_searchbnf_conf.py): The syntax generation maps Float to <int> — this is misleading. Float validator should produce <float> or <number> in the syntax, not <int>.

3. Duration mapped to <int> (create_searchbnf_conf.py): Similarly, Duration values are mapped to <int> but durations typically have formats like 5m, 1h — consider <duration> instead.

4. syntax no longer required (global_config_validator.py): The validation was changed to only require description and usage when requiredSearchAssistant is True, removing syntax from the required set. However the error message still says "One of the attributes among description, usage, syntax". The error message should be updated to match the new requirement.

5. Magic number 120/100 for line wrapping (create_searchbnf_conf.py): The syntax line-wrapping uses hardcoded thresholds of 120 and 100 characters. These should be named constants or at least documented in a comment explaining why these values were chosen.

6. maxLength: 100 removed from syntax schema (schema.json): The maxLength constraint was removed from the syntax field. Since auto-generated syntax can exceed 100 chars (hence the line-wrapping logic), this makes sense, but it also means manually provided syntax strings are no longer validated for length. Was this intentional?

The feature is well-designed overall and the test coverage is good, especially the auto-generation test case with mixed validators.

[kkedziak-splunk]

Bug: This chain of if statements should be elif. Currently, every condition is evaluated even after a match, and param_syntax could be silently overwritten. For example:

if validator in ("Integer", "Float", "Duration"):
    param_syntax = ...
elif validator == "Boolean":
    param_syntax = ...
elif validator == "Set":
    ...

Without elif, this works only by coincidence (no validator matches multiple branches), but it's still a correctness issue and a performance waste.

[kkedziak-splunk]

Float and Duration are both mapped to <int> which is misleading. A float parameter should show <float> or <number> in syntax, and duration should show <duration> to hint at formats like 5m, 1h, etc.

[Benni0]

Only <int> is documented in searchbnf.conf documentation. I'm quite sure it wouldn't have any impact, if we introduce new keywords like <float> or <duration>.

I guess this issue was created by AI, wasn't it?
What's your opinion on this?

[kkedziak-splunk]

Magic numbers 120 and 100 for line wrapping. Consider extracting these as named constants (e.g. MAX_SYNTAX_LINE_LENGTH = 120) and adding a comment explaining the rationale.

[kkedziak-splunk]

The error message on the next line still references syntax as required: "One of the attributes among description, usage, syntax". Since syntax is no longer required (it's auto-generated), this error message should be updated to match.