Req - Requirements engineering without the frills

Req is a deliberately ultra-minimalist requirement management tool.

It is inspired by tagref and adds the notions of requirement sets and relations.

I wrote several tools (e.g. yreq) to deal with requirements. req is an attempt to replace tagref in the process described in Simplify your project documentation: Markdown + forge, that’s all you need.

Support

If you like req (or LuaX) and are willing to support its development, please consider donating:

Installation

req requires LuaX.

# install req in ~/.local/bin
git clone https://codeberg.org/cdsoft/req
cd req
bang && ninja install

or set $PREFIX to install req to a custom directory ($PREFIX/bin and $PREFIX/lib):

export PREFIX=/path # install req to /path/bin
git clone https://codeberg.org/cdsoft/req
cd req
bang && ninja install

This will install 2 files in $PREFIX/bin:

1. $PREFIX/bin/req: req command line utility compiled with LuaX. It can be run without any dependency.
2. $PREFIX/bin/req.lua: req.lua command line utility bundled with LuaX as a standalone Lua script. It requires a Lua 5.4 or 5.5 interpreter (e.g.: lua).

In case precompiled binaries are needed (GNU/Linux, MacOS, Windows), some can be found at cdelord.fr/pub. These archives contain req as well as some other softwares more or less related to LuaX.

Usage

$ req -h
Usage: req [-h] [-v] [-c <conf.toml>] [-o <file>] [-M <file.d>] [-f]

Req is an ultra-minimalist requirement management tool.

Options:
   -h, --help            Show this help message and exit.
   -v, --version         Show req version
   -c <conf.toml>        Use a specific configuration file (default: req.toml)
   -o <file>             Output file (Plain text, Markdown, Lua, JSON)
   -M <file.d>           Save dependencies to a make dependency file (-o must be provided)
   -f                    Fail on error

For more information, see https://codeberg.org/cdsoft/req

req just does one thing: it scans files for requirements and checks the requirement graph. It lists duplicate, unknown and unused requirements.

Definitions

req is inspired by tagref. It reuses the notion of tags (requirements) and references with a similar syntax. req builds and checks a requirement graph.

Requirements

In engineering, a requirement is a condition that must be satisfied for the output of a work effort to be acceptable. It is an explicit, objective, clear and often quantitative description of a condition to be satisfied by a material, design, product, or service.

– Wikipedia

With req a requirement is a piece of specification/code/test/… It is identified by a requirement marker. A requirement starts with a user-defined tag (a noun). It takes a requirement identifier (a string). E.g.:

    [noun:identifier]

References

A reference is an oriented link from the current location to an upstream requirement. A reference starts with a user-defined tag (a verb). It takes a requirement identifier (a string). E.g.:

    [verb:identifier]

In this example, [verb:identifier] refers to [noun:identifier] in an upstream document.

This syntax is compatible with tagref.

Requirement set

A requirement set is a set of requirements of the same nature, defined in a set of documents. These can be sets for specification requirements, test requirements, implementation requirements…

Relation

A relation is a link between between two requirement sets that defines the nature of the relation between two requirements. It is actually a mathematical relation, a relation being a set of references between two sets of requirements. E.g.: a requirement can refine/implement/validate another requirement.

Configuration

The configuration file is a TOML file that defines:

• the sets of requirements, represented by a set of files that can be used as upstream/downstream documents
• relations between upstream/downstream sets of requirements

The default configuration file is req.toml.

Sets of requirements

[spec:set_specification]

The set table contains tables (one per set) defining the set name and its files:

[set."Set Name"]
noun = "set-noun"
path = [ "path1", "path2"... ]
include = [ "pattern1", "pattern2"...]
ignore = [ "pattern1", "pattern2"...]

The files of a set are collected recursively in all directories listed in the path attribute. In a git repository, only files belonging to the repository are listed.

The include field is an optional list of file patterns to include ([spec:included_files]).

The ignore field is an optional list of file patterns to ignore ([spec:ignored_files]).

[spec:ignore_preprocessed_files]

When the include parameter contains files or patterns ending with .in (files traditionally meant to be preprocessed, e.g. *.md.in) then the corresponding preprocessed files (without the .in extension) are ignored.

Relations

[spec:relation_specification]

The relation table contains tables (one per relation) defining the relation name and the upstream/downstream sets of files:

[relation."Relation Name"]
verb = "relation-verb"
up = "Upstream set name"
down = "Downstream set name"

Example

See the req configuration file.

Configuration properties

req shall check the configuration consistency:

[spec:check_missing_conf]

The configuration file shall exists.

[spec:check_missing_path]

Paths in sets definitions shall exists.

[spec:check_missing_sets]

The relations shall reference existing sets.

Requirement properties

The requirements and references shall meet certains conditions:

[spec:unique_identifiers]

Identifiers in a set of requirements must be unique.

[spec:report_unknown_requirements]

Requirements that are referenced but not defined must be reported as an error.

[spec:report_unused_requirements]

Upstream requirements that are defined but not referenced must be reported as an error.

Coverage report

The final report shall contain:

[spec:error-report]

All errors listed in Requirement properties.

[spec:coverage-report]

Coverage summary by relations (total coverage, number of requirements (total and covered)).

License

req is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

req is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with req.  If not, see <https://www.gnu.org/licenses/>.

For further information about req you can visit
https://codeberg.org/cdsoft/req