L.O.B.S.T.E.R.

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 requirements manager I want the traceability report to mention the
codebeamer link to each requirement in codebeamer.

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.

As a user of lobster-codebeamer
I want to fetch items from a codebeamer baseline
so that I can create a traceability report for a baseline.

For each request sent to codebeamer, IF a token is configured,
THEN the tool shall send the token as Bearer authentication,
regardless of whether a user and/or password are also configured.

Note: "configured" means the data is available in the configuration file.

For each request sent to codebeamer, IF no token is configured,
AND a complete user/password pair is configured,
THEN the tool shall send those credentials using HTTP Basic authentication.

For each request sent to codebeamer, IF neither a token nor a complete
user/password pair is configured,
AND the user's .netrc file contains an entry matching the configured
codebeamer root's hostname with a login and password,
THEN the tool shall send those credentials using HTTP Basic authentication.

IF no usable token or user/password pair is configured,
AND the user's .netrc file is absent or has no usable entry matching the
codebeamer server hostname,
THEN the tool shall print an error message to STDERR
AND exit with a non-zero return code.

IF the yaml config file option "baseline_id" is present,
AND the option "import_query" is a cbQL query string,
THEN the tool shall append the "baselineId" parameter, with the configured
value, to the payload of every request sent to the codebeamer server for that query.

IF a query (given by id or by cbQL string) is executed,
THEN the tool shall fetch every page of results reported by the codebeamer server
AND shall write to the output file exactly the items reported across all pages,
each with the id, name, and version as received from the server.

IF an element given through the yaml config file option "import_query" is a valid codebeamer query id
(integer greater than zero),
THEN the tool shall request items from the codebeamer server with the given query id
according to [[Paginated_Query_Extraction_Correctness]]
AND write the obtained codebeamer items in the LOBSTER interchange format to the file given in the "out" parameter

IF an element given through the yaml config file option "import_query" is valid
codebeamer query string,
THEN the tool shall request items from the codebeamer server with the given query
string according to [[Paginated_Query_Extraction_Correctness]]
AND write the obtained codebeamer items in the LOBSTER interchange format to the file
given in the "out" parameter.

The tool shall include, in the location of each generated LOBSTER item,
a reference to the originating codebeamer item consisting of the codebeamer
root URL, tracker id, item id, and item version.

IF the configuration parameter "import_query" and "import_tagged" are both not
provided (either missing in the configuration file or set to an empty string),
THEN the tool shall display an error message and exit with a non-zero return code.

IF the configuration file cannot be opened,
THEN the tool shall print an error message to STDERR
AND exit with return code 1.

IF the configuration file contains an unsupported key,
THEN the tool shall print an error message to STDERR identifying the unsupported key
AND exit with return code 1.

IF the codebeamer server returns an empty list as (a result of the query),
THEN the tool shall display a message to the user.

IF an element given through the configuration option "refs" is a list of codebeamer
field names,
THEN the tool shall extract the corresponding references from the given codebeamer
item fields,
either from a same-named top-level field on the item or, if that field is absent or empty,
from a "customFields" entry with a matching name,
AND add a Tracing_Tag entry to the LOBSTER item for each referenced item ID.

Note: Here the term "item" refers to a codebeamer JSON item as returned by the server
through its API.

The function "get_authentication" SHALL return a BearerAuth instance built from
the configured token, IF a token is configured, regardless of whether a user
and/or password are also configured.

OTHERWISE (no token is configured), the function "get_authentication" SHALL
return an HTTPBasicAuth instance built from the configured user and password,
even if either of them is missing.

The function "update_authentication_parameters" SHALL raise KeyError,
IF no token is configured,
AND no user/password pair is configured,
AND no .netrc entry matching the configured root's hostname is found.

IF a token is configured, OR a user/password pair is configured,
THEN the function "update_authentication_parameters" SHALL leave the
configuration unchanged, without consulting a .netrc file, even IF one exists
with a matching entry.

IF neither a token nor a user/password pair is configured,
THEN the function "update_authentication_parameters" SHALL look up the hostname
of the configured root (ignoring any sub-path) in the .netrc file,
AND SHALL use the matching entry's login and password.

IF a .netrc file is consulted but contains no entry matching the configured
root's hostname,
THEN the function "update_authentication_parameters" SHALL raise KeyError,
identifying the expected hostname and the machine names actually found.

The function "load_config" SHALL raise FileNotFoundError,
IF the given config file path does not exist.

The function "load_config" SHALL raise OSError,
IF the given path is a directory instead of a file.

The function "parse_config_data" SHALL raise KeyError, identifying the
unsupported key(s),
IF the config data contains any key that is not listed in
"SupportedConfigKeys".

The function "parse_config_data" SHALL raise KeyError,
IF neither "import_tagged" nor "import_query" is provided,
OR "import_query" is provided as an empty string.

The "base" property of the "Config" class SHALL return the configured root URL with
"/api/v3" appended.

The function "get_query" shall print a message to the user IF the query returns zero items.

The function "get_query", IF the parameter "query" is an integer,
SHALL request items from the "reports/<query>/items" endpoint
AND SHALL return a list of each codebeamer item converted to a LOBSTER item.

The function "get_query", IF given the parameter "query" is a string,
SHALL request items from the "items/query/?queryString=<query>" endpoint
AND SHALL return a list of each codebeamer item converted to a LOBSTER item.

The function "get_query" SHALL append the "baselineId" parameter to the
request URL, IF a baseline id is configured AND the query is a cbQL string,
AND SHALL NOT append it, IF the query is an integer query id.

The function "get_query" SHALL raise MismatchException,
IF the codebeamer server reports a "total" item count that does not match the
number of items actually returned across all fetched pages.

The function "get_many_items" SHALL request, across as many pages as needed,
all items whose id is contained in the given collection of item ids.

The function "import_tagged" SHALL fetch the given list of items from codebeamer
AND SHALL return a list of each of them converted to a LOBSTER item.

The function "to_lobster" SHALL populate the generated LOBSTER item's location
with the configured codebeamer root, and the tracker id, item id, and version
taken from the codebeamer item.

The function "to_lobster", for each field name configured via "refs",
SHALL add a reference to the generated LOBSTER item for every value found at a
same-named top-level field of the codebeamer JSON item,
OR, IF that field is absent or empty, for every value found in a "customFields"
entry with a matching name.

The "to_lobster" function shall call the optional "item_to_text" delegate
with each raw Codebeamer item and shall assign its returned string to the
text field for Requirement and Activity items.

Note: This implies the delegate is not called for Implementation items.

The "lobster_codebeamer" function shall propagate an exception raised by
the "item_to_text" delegate without catching it.

The "get_query" function shall pass its "Config" object unchanged to
each invocation of the "to_lobster" function.