Requirements Reader
The requirements reader turns a build-published requirement export into Requirement records. It reads the export a documentation build wrote, not the source files the build read, and it accepts that export only when the build was reproducible, because a hash over content that changes between two builds of one commit would prove nothing. It serves this repository’s own export and any other producer’s the same way; which need types are Requirements is configuration, never inference.
A Requirement’s content is what its authors wrote: the title, the statement
and the links to its parent requirements. A parent link is a link from a
need to a requirement it refines. The export holds parent links in one need
field, which the configuration names; the field called refines is the
default, and a producer may use another name, such as trace. Its status and tags change as a
review moves, without the statement changing, so they are metadata; so are
the back-links, sections, positions and rendering the build derives. Because
the hashed form is built from the export, the anchor below names the source
file that form is built from; recomputing the hash needs the build. Where a
source map is configured, the anchor names the authored source file that the
map gives for the need’s document. The hash still comes from the export and
never from that file.
The requirements reader shall supply Requirement records from the requirement export it is given. |
The requirements reader shall supply a Requirement record for a need when, and only when, the need’s type is one of the requirement types it is configured with. |
The requirements reader shall identify each Requirement record by the identifier of its need, verbatim. |
The requirements reader shall compute each Requirement’s content hash from the canonical serialization of the need’s title, content and parent links, and from no other field of the need. |
The requirements reader shall compute the same content hash for a need irrespective of the order in which the export lists its parent links. |
The requirements reader shall derive Refines edges from the parent links each need declares, and from no back-link field. |
If the requirement export carries a build timestamp, then the requirements reader shall refuse the export instead of supplying records from it. |
Where a source directory is configured, the requirements reader shall anchor each Requirement’s content hash at the need’s source file within the repository configured for the requirements reader, the file the need’s docname and doctype name under the source directory, with the locator need:<need identifier>. |
The requirements reader shall take each need’s parent links from the need field it is configured with. |
While no parent-link field is configured, the requirements reader shall take each need’s parent links from the need field named refines. |
Where a source map is configured, the requirements reader shall anchor each Requirement’s content hash at the source file the map names for the need’s docname, with the locator need:<need identifier>. |
If a source map is configured and does not name a source file for the docname of a need of a configured type, then the requirements reader shall refuse the export, naming every such docname. |
Software Requirement: Every misshapen need of the requirement export is reported in one error SEG-SREQ-352
|
If one or more needs of the requirement export lack a text field the requirements reader reads, declare an id other than their key, or carry a parent-link field that is not a list of identifiers, then the requirements reader shall report every such need in one error, each with its reason. |