As a traceability manager I want the traceability report to list items that fulfill the tracing policy, and how they do so, so that I can decide whether to release my product.
Example: If the tracing policy is: Tests --(trace to)--> Requirements, then the report shall list all tests that link to at least one requirement, and the report shall list all linked requirements per test.
The use case applies to the reverse direction as well.
As a traceability manager I want the traceability report to list items that are not covered by other items, where coverage rules are specified by the tracing policy, so that I can identify gaps in the coverage.
Example: If the tracing policy is: Tests --(trace to)--> Requirements, then the report shall list all tests that do not link to any requirement.
The use case applies to the reverse direction as well.
As a traceability manager I want the traceability report to show the fraction of the number of items in one level (of the tracing policy) which fulfill the tracing policy, divided by the total number of items in that level (of the tracing policy). The fraction shall be shown as percentage.
Example: If the tracing policy is: Tests --(trace to)--> Requirements, then the report shall show the fraction of requirements which are covered by at least one test, divided by the total number of requirements.
As a CI administrator I want that the tool exits with a non-zero return code whenever it encounters invalid input so that the CI pipeline can catch invalid input automatically.
As a user of LOBSTER I want to have a good usability and standard command-line ergonomics, like built-in help or automatic creation of output destinations, so that using the tools is intuitive and seamless in scripts and interactive use.
IF the file given through the command line option "--config" does not exist, THEN the tool SHALL print an error message stating that the file was not found to STDERR AND SHALL exit with a non-zero return code.
IF the file given through the command line option "--config" does not conform to the expected schema (defined in the file "schema.yamale"), THEN the tool SHALL print an error message identifying the schema violation to STDERR AND SHALL exit with a non-zero return code.
IF a configured conversion rule's package and record-type does not match any TRLC record type found in the consumed input, THEN the tool SHALL print an error message listing the unmatched rule(s) to STDERR AND SHALL exit with a non-zero return code.
IF a conversion rule references a field (for example, in "description-fields" or "tags") that does not exist on the matched TRLC record object, THEN the tool SHALL print an error message identifying the missing field and the record object to STDERR AND SHALL exit with a non-zero return code.
IF a conversion rule references a tuple-typed field, AND no "to-string-rules" entry is configured for that tuple type, THEN the tool SHALL print an error message identifying the tuple type, its value, and the location where it is used, to STDERR AND SHALL exit with a non-zero return code.
IF a tuple type has one or more configured "to-string-rules" entries, AND every configured rule fails to apply (for example because it references a field that does not exist on the tuple), THEN the tool SHALL print an error message identifying the tuple type and value to STDERR AND SHALL exit with a non-zero return code.
IF a tuple type has one or more configured "to-string-rules" entries, AND at least one of them can be applied to a given tuple value (trying the configured rules in order), THEN the tool SHALL use the text produced by the first applicable rule as the string representation of that value.
IF a conversion rule is configured for a TRLC record type, AND the rule's "applies-to-derived-types" option is true (the default), THEN the tool SHALL also apply that rule to every record type that directly or indirectly extends the configured type, UNLESS a more specific rule is configured for the derived type. OTHERWISE (the option is false), THEN the rule SHALL only apply to the exact configured type.
IF the list elements given through the config option "inputs" are files with extension rsl, trlc and trlc.md, THEN all files given in "inputs" parameter shall be consumed.
IF one or more DIR or FILE positional command line arguments are given, THEN the tool SHALL process them as additional inputs, applying the same rules as for the config option "inputs".
IF an input element, given through "inputs", "inputs_from_file", or a positional command line argument, is neither a file nor a directory, THEN the tool SHALL terminate with a non-zero return code, without generating output.
IF the element given through the config option "inputs_from_file" is a file, THEN each line in that file shall be interpreted as a path AND shall be consumed.
IF both the config options [[Input_List_Of_Files]] AND [[Inputs_From_File]] are provided, THEN all files given in [[Input_List_Of_Files]] AND [[Inputs_From_File]] parameter shall be consumed.
IF a list element given through the config option "inputs" is a directory, THEN the tool SHALL recursively search that directory AND SHALL treat every file found with a valid extension (".rsl", ".trlc", ".trlc.md") as an additional input file.
IF an input file, given through "inputs", "inputs_from_file", or a positional command line argument, does not have one of the valid extensions (".rsl", ".trlc", ".trlc.md"), THEN the tool SHALL print an error message identifying the file and the expected extensions to STDERR AND SHALL exit with a non-zero return code.
IF the consumed input files contain duplicate definitions of the same TRLC identifier, THEN the tool SHALL print the locations of the duplicate and the original definition to STDOUT, SHALL print "aborting due to TRLC error" to STDERR, AND SHALL exit with a non-zero return code, without generating output.
IF the consumed input files contain zero TRLC record objects (for example because no ".trlc" files were given, only ".rsl" schema files), AND every configured conversion rule matches at least one TRLC record type, THEN the tool SHALL write zero items to the output AND SHALL exit with return code 0.
Note: [[Orphan_Conversion_Rule_Error]] describes the behavior if at least one conversion rule does not match any TRLC record type.
If an output file is specified as a command line argument, then the output SHALL be written to that file. Otherwise, the output SHALL be written to 'trlc.lobster'.
Output content: The tool SHALL populate each generated LOBSTER item's tag, location, and description fields using the data from the single corresponding TRLC record object.
IF the consumed input contains a TRLC record object whose type matches a configured conversion rule, THEN the tool SHALL generate exactly one LOBSTER item for that record object. The generated item's tag, source location, and description SHALL be derived from that same record object.
IF a command line argument is prefixed with "@", THEN the tool SHALL read the contents of the file named by the remainder of that argument, and SHALL include each of its contained arguments as if they had been given directly on the command line.
If the conversion rule configuration contains a "version-field: xxx" entry and the record object has a field named "xxx", then the tool shall set the tag version to the value of that field.
If the conversion rule configuration contains a "version-field: xxx" entry but the record object does not have a field named "xxx", then the tool shall set the tag version to None.
If the conversion rule configuration does not contain any "version-field: xxx" entry, then the tool shall set the tag version to None, regardless of the record object.
The method LobsterTrlcConfig.from_file SHALL raise YamaleError, identifying the schema violation, IF the config file does not conform to the expected YAML schema.
Given a schema-valid configuration file, the method LobsterTrlcConfig.from_file SHALL create one ConversionRule object for each "conversion-rules" entry and one ToStringRules object for each "to-string-rules" entry, with each object's fields populated from its corresponding entry.
The constructor of the class Converter SHALL raise InvalidConversionRuleError, identifying the offending rule(s), IF a configured conversion rule's package and record-type does not match any TRLC record type found in the given symbol table.
The method Converter.generate_lobster_object SHALL raise RecordObjectComponentError, identifying the field name, IF a conversion rule references a description, tag, or justification field that does not exist on the matched TRLC record object.
The method Converter.generate_lobster_object SHALL format multiple configured description fields as "field_name: text" pairs, separated by an empty line, but shall skip any description fields that are not present on the matched TRLC record object.
The method Converter.generate_lobster_object SHALL use the text produced by the first applicable configured to-string rule as the value of an unresolved reference, IF a tag field is tuple-typed.
The method Converter.generate_lobster_object SHALL raise TupleToStringMissingError IF a tag field is tuple-typed and no to-string rule is configured for that tuple type.
The method Converter.generate_lobster_object SHALL raise TupleToStringFailedError IF a tag field is tuple-typed and every configured to-string rule for that tuple type fails to apply.
The method Converter.generate_lobster_object SHALL populate the generated item's just_up, just_down, and just_global lists from the configured justification fields, applying the same field-to-text conversion rules as for tags.
The method Converter.generate_lobster_object SHALL set the generated item's tag version to the value of the configured version field, IF a version field is configured and present on the matched TRLC record object.
The method Converter.generate_lobster_object SHALL set the generated item's tag version to None, IF a version field is configured but not set on the matched TRLC record object.
The method Converter.generate_lobster_object SHALL set the generated item's tag version to None, IF no version field is configured, regardless of the matched TRLC record object.
The method Converter._generate_text SHALL return a list containing the string representation of a scalar field's value, OR the string representation of every element, IF the field is an array.
The method Converter._generate_text SHALL raise TupleToStringMissingError, IF a tuple-typed field has a value, but no to-string rule is configured for that tuple type.
The method Converter._generate_text SHALL convert a tuple-typed field's value to text by applying the configured to-string instructions for that tuple type.
The method Converter.generate_lobster_object SHALL omit a configured field from the generated item's description, tags, and justifications, IF that field is optional in the TRLC schema and not set on the record object.
The function build_record_type_to_conversion_rule_lookup SHALL map every TRLC record type, direct or indirect, extending a configured type to that type's conversion rule, IF the rule's applies_to_derived_types option is true.
The function build_record_type_to_conversion_rule_lookup SHALL map a TRLC record type to the conversion rule configured for that exact type, IF such a rule exists, even though an ancestor type also has a propagating rule configured. The result SHALL NOT depend on the order of the given conversion rules.
The function build_record_type_to_conversion_rule_lookup SHALL map only the exact configured TRLC record type to its conversion rule, and SHALL NOT map any derived type to it, IF the rule's applies_to_derived_types option is false.
The error classes TupleToStringFailedError, TupleToStringMissingError, and TupleComponentError SHALL format an error message containing the tuple type name, the tuple's value, and the source locations of both the tuple's usage and its type definition.
The class ItemWrapper SHALL return the Python value, the raw TRLC AST value, and the Python value (or None) of an existing field, through get_field, get_field_raw, and get_field_value_or_none respectively.
The class ItemWrapper SHALL raise RecordObjectComponentError from get_field and get_field_raw, AND SHALL return None from get_field_value_or_none, IF the requested field does not exist on the wrapped TRLC record object.
The configured to-string instructions of a ToStringRules entry SHALL be applied to convert a single tuple-typed field's value to its string representation.
The configured to-string instructions of a ToStringRules entry SHALL be applied to every element of a tuple-array-typed field, and the resulting strings SHALL be presented in the same order as they occur in the input.
The function build_tuple_type_to_ruleset_map SHALL map every TRLC tuple type found in the symbol table that has a matching configured ToStringRules entry (by package and tuple-type name) to that entry.
The method FileCollector.add_file SHALL add a file to its "files" list, IF the file's extension is one of the configured extensions. OTHERWISE, THEN the method SHALL silently ignore the file, UNLESS "throw_on_mismatch" is true, in which case it SHALL raise PathError, identifying the file and the expected extensions.
The method FileCollector.add_file SHALL treat a multi-part configured extension (for example ".trlc.md") as matching only files whose full compound suffix is equal to it, and NOT as matching by the last suffix alone.
The function create_worklist SHALL raise ValueError, identifying the offending element, IF an input element is neither an existing file nor an existing directory.
The function combine_all_inputs SHALL include the given positional "dir_or_files" arguments in its returned list of inputs, in addition to the config's "inputs" and "inputs_from_file" entries.
The function combine_all_inputs SHALL include every non-empty, non-comment line of the file named by config.inputs_from_file in its returned list of inputs.
The function combine_all_inputs SHALL include both config.inputs and the contents of config.inputs_from_file in its returned list of inputs, IF both are given.
The function create_worklist SHALL recursively search a directory input for files matching the tool's configured extensions, and SHALL ignore any other file found there.
The tool SHALL register the command line option "--config" as a required argument of its argument parser, so that parsing the command line without it SHALL fail.
The method LOBSTER_Trlc.run_lobster_trlc SHALL raise TrlcFailure, IF the TRLC Source_Manager fails to process the consumed input files (for example, because they contain duplicate definitions).
The function parse_instructions SHALL split a to-string instruction text into constant-text and field instructions, identifying every "$(field_name)" placeholder as a field instruction and everything else as a constant-text instruction.
The function build_text_from_instructions SHALL raise ValueError, IF the tuple data is empty, the instruction sequence is empty, or an instruction has a type other than CONSTANT_TEXT or FIELD.
OTHERWISE (the tuple data and instruction sequence are non-empty), the function SHALL raise TupleComponentError IF a field instruction references a tuple component that has no value in the tuple data.
OTHERWISE (tuple data and instructions are valid and non-empty, and referenced tuple components have values), THEN the function build_text_from_instructions SHALL return a string formed by processing instructions in order.