[](https://crates.io/crates/reqtk)
[](https://crates.io/crates/reqtk)
[](https://docs.rs/reqtk/latest/reqtk/)
[](LICENSE.md)
[](REQUIREMENTS.md)
# Req Toolkit
ReqTk is a requirements management toolkit built around a human-readable, git-friendly `.req` file format. Define, validate, format, trace, transform, and convert requirements directly from your repository.
> ⚠️Experimental! \
> ReqTk is still under development and is missing some
> critical tests. Data loss is possible. Keep backups and report bugs.
VSCode extension is coming soon!
## Design goals
- Human readable (good git-diffs)
- Hierarchical structure
- Possibility for custom attributes (e.g. multiple-languages, tags, etc.)
- IDE support possibility
- AI friendly (e.g. tooling to search requirements)
- Conversion from existing requirement formats
- Easy way to publish for open-source projects (markdown conversion)
- Tracing (to other requirements, to tests, to issues)
- CI support (format, check)
- History (from git)
## Getting started
1. Install `cargo` ([instructions](https://doc.rust-lang.org/cargo/getting-started/installation.html))
2. Run `cargo install reqtk`
3. Navigate to your project's root directory.
4. Run `reqtk init`
- This will create `reqtk.json` and `requirements.req`.
- Adjust the source and requirement file paths to your needs.
`init` will generate the following req file:
```text
[id-type=incremental]
[id-prefix=REQ-]
[id-count=2]
@REQ-1(My requirement) {
[type=functional]
[description]
Hello world!
[/description]
}
```
### Generate markdown
You can generate markdown from your requirements using: \
`reqtk convert -o REQUIREMENTS.md`
### Reflow ids in your requirement file
Before first commit you might want to re-assign the ids in your docment incrementally using: \
`reqtk transform --id incremental --prefix MYREQ-`
## ReqTk usage
```text
ReqTk is a requirements management toolkit built around a human-readable, git-friendly `.req` file format.
Usage: reqtk [OPTIONS] <COMMAND>
Commands:
format Format req files
check Analyze req files for issues
convert Convert between known requirement formats (req, json)
transform Transform a req file (e.g. reflow ids, minify)
tokenize Tokenize a req file (output: JSON)
trace Find traces for requirements (output: JSON)
find Finds a single requirement (output: JSON)
init Initializes a reqtk.json workspace file
help Print this message or the help of the given subcommand(s)
Options:
-r, --report <REPORT> Issue reporting format [default: human] [possible values: human, json]
-v, --verbose Enable verbose output
-h, --help Print help
-V, --version Print version
Input location ([INPUTS]):
MISSING → inputs from nearest 'reqtk.json' workspace file
PATH → use the given files
reqtk.json → load files from the provided workspace file
- → stdin
Output location (-o, --output):
MISSING → output to default location
(same as input, extension is changed to match the output format)
e.g. file.req → file.tokens.json, stdin → stdout
PATH → output location (only when one input is provided)
- → stdout
```
# REQ file format
## Req file elements
### Attributes
Single line attribute:
```text
[key=value]
```
Multi-line attribute:
```text
[key]
multi
line
value
[/key]
```
Attributes can be placed at root level or inside other elements (see later).
Root level attributes:
| id-type | `incremental`, `incremental-N`, `random`, `random-N`, where N is an integer | Type of the requirement IDs. Used by IDE's to generate the identifiers for new requirements. |
| id-prefix | string | Prefix of the requirement IDs. Type of the requirement IDs. Used by IDE's to generate the identifiers for new requirements. |
| id-count | unsigned integer | Only used when `id-type`=`incremental*`. Contains the counter for incremental requirement IDs. Used by IDE's to generate the identifiers for new requirements. |
### Requirement types
You can define your own requirement types with the following syntax (root level):
```text
$custom(Custom) {
[icon=star]
[color=yellow]
[has-children=true]
}
```
Requirement type attributes:
| icon | [material icon](https://fonts.google.com/icons?icon.set=Material+Icons&icon.style=Filled) | Icon of the requirement type. |
| color | html/css color | Color of the icon. |
| has-children | `true`/`false` | Allow the IDE to add children to the requirement. |
The following requirement types are built-in:
|  | folder | Folder | true | (default) |
|  | functional | Functional | false | |
|  | informative | Informative | false | |
|  | parameter | Parameter | false | |
|  | limitation | Limitation | false | |
### Requirements
You can add requirements with the following syntax:
```text
@parent(Parent) {
@child(Child) {
[type=functional]
[description]
Hello world!
[/description]
}
}
```
Requirement attributes:
| type | `folder` (default), `functional`, `informative`, `parameter`, `limitation` or the identifier of a custom requirement type | Requirement type. |
| description | markdown text | Requirement description. |
The requirement description supports references to other requirements in the following format:
```text
@REQ-1(First) {
[type=functional]
[description]
This is a reference to {@REQ-2}
[/description]
}
@REQ-2(Second) {
[type=functional]
[description]
This is a reference to {@REQ-1}
[/description]
}
```
The traces will show up in the `reqtk trace` command.