Configuration

Users can configure trudag by providing a config.toml file or pointing the TRUDAG_CONFIG environment variable to a config.toml file.

Users can also omit passing a configuration file, and rely solely on the command-line options given to trudag.

If no command-line options or custom configuration file paths are provided, trudag will fallback to an in-built default configuration.

The configuration file is based on the following schema:

Name	Type	Default Value	Description
publish	`PublishOptions`	see publish section for default values	Options to configure publishing of Trustable Report(s) (see publish section).
artifact	`ArtifactOptions`	see artifact section for default values	Options to configure exporting and importing of Trustable artifacts (see artifacts section).
scoring	`ScoringOptions`	see scoring section for default values	Options to configure the calculation of Trustable Scores (see scoring section)
plot	`PlotOptions`	see plot section for default values	Options to configure the output plots of the Trustable project (see plot section).
tooling	`ToolingOptions`	see tooling section for default values	Options to configure the `trudag` tooling while running commands (see tooling section).

Publish

Options for configuring publishing of reports:

Name	Type	Default Value	Description
reports	`list[ReportOptions]`	see default report configuration	Configuration for each report, indexed by report name (see reports sub-section).
output_path	`Path`	`./docs/trustable`	The parent path to output all the published reports. (see report sub-section).

Report

Each Trustable report can be divided into the following customisable sections:

A preamble text section at the top of the report:
- Example: Item Status guide in the current report.
An afterword text section at the bottom of the report:
- Example: The default configuration showcases the report afterword
The document view containing the document section title and the table of items underneath the document:
- Example: Compliance for TA in the current report.
An Item summary view containing information about an item:
- Example: TA-ANALYSIS in the current report.
A dashboard file:
- Example: Dashboard file in the current report.

Every report generated (individually or in batches) can be customised with unique section configurations.

These options are related to only customising the structure of the published reports and not the format in which the report needs to be published.

Name	Type	Default Value	Description
root	`str \| None`	`None`	The root node item to start the report from when publishing
name	`str`	`Software`	Report name to publish.
include_non_normative	`bool`	`False`	Include text of non-normative items.
figures	`FiguresOptions`	`FiguresOptions`	see figures section
score_tables_enable	`bool`	`False`	Include table of historic scores in report.
preamble	`str`	see default report configuration	The report's preamble text (The text at the top in the main report file)
documents	`dict[str, DocumentOptions]`	`{"TA": DocumentOptions(),"TT": DocumentOptions(),"TRUSTABLE": DocumentOptions(),}`	The options to configure each document view section. (see default report configuration for an example)
afterword	`ReportAfterword`	`ReportAfterword`	see report afterword section

Figures

This sub-section deals with setting options for the historical figures attained from the data store.

These figures are displayed in the report's item summaries and dashboard page.

Name	Type	Default Value	Description
enable	`bool`	`False`	Include graphs in reports (requires configured data store)
data_rows_limit	`int`	`20`	Maximum number of data rows to include in the figures

Documents

The documents view is the central view in the published report showcasing the item scores and information across multiple Trustable documents.

The following options are supported for this view:

Name	Type	Default Value	Description
title	`str \| None`	`None`	Title text for the title ending in the document name for each document section (e.g. "Compliance for" as the default).
preamble	`str \| None`	`None`	Preamble text for each document section
afterword	`str \| None`	`None`	Afterword text for each document section
mappings	`MappingOptions`	`MappingOptions`	Custom table header replacement names as value for existing table headers names as keys. If a valid key is passed with an empty value, that column is omitted from the table. see mappings section

Info

The names of document mappings should be the ones you use in your own Trustable Graph. The default values are for the Trustable Graph (TSF).

Mappings

Name	Type	Default Value	Description
item	`str`	`Item`	Header text for the `Item` column
summary	`str`	`Summary`	Header text for the `Summary` column
score	`str`	`Score`	Header text for the `Score` column
score_origin	`str`	`Score Origin`	Header text for the `Score Origin` column
status	`str`	`Status`	Header text for the `Status` column

Afterword

Name	Type	Default Value	Description
text	`str`	""	Afterword text in the main report
include_metadata	`bool`	`True`	Include/exclude metadata information about the Trustable project in the main

Artifacts

The artifacts process also requires certain options to be set for importing/exporting artifacts correctly.

Name	Type	Default Value	Description
import_options	`ArtifactImportOptions`	(see import sub-section)	Options for importing of remote graphs/artifacts in the local Trustable project (see import sub-section).
export_options	`ArtifactExportOptions`	(see import sub-section)	Options for exporting of remote graphs/artifacts from the local Trustable project (see export sub-section).

Import

For each imported remote graph, the following options can be configured:

Name	Type	Default Value	Description
path	`Path`	`Software.json`	The artifact file path to consume the Trustable remote graph.
namespace	`Path \| None`	`None`	The namespace to be set when importing the items from the Trustable remote graph.
import_dir	`Path \| None`	`None`	The output directory path to import the needs/AOU items.

Export

To export the current Trustable project the following options are required to be configured:

Name	Type	Default Value	Description
path	`Path`	`Software.json`	Output file path to export the current project's artifact file.
name	`str`	`Software`	The name of the project that is to be exported.
allow_failure	`bool`	`False`	Allow/Disallow exporting the artifact even if some needs items have failed references.
include_data_store	`bool`	`False`	Include the project's data store in the artifact.

Scoring

Different options for scoring can be provided for example to run the validators provided, or to specify a scores dump file path for the Data Store

Name	Type	Default Value	Description
dump	`Path \| None`	`None`	Output file path for the Trustable Scores file, currently supports .csv and .json file extensions or a configured data store
enable_validators	`bool`	`True`	Enable/Disable the validators during the Trustable scoring process.
concurrent_validation	`bool`	False	Run validators concurrently.
sensitivities	`SensitivitiesOptions`	see sensitivities section	Options to configure item sensitivities
scoring_decimal_precision	`int`	`5`	Precision for item scores

Sensitivities

Name	Type	Default Value	Description
enable	`bool`	`False`	Includes sensitivity analysis as part of the report.
decimal_precision	`int`	`5`	Precision for item sensitivities.
data_rows_limit	`int`	`20`	Maximum number of data rows to include in the sensitivities table.

Plot

The Trustable graph which stores all the information about statements and can also be plotted with customisations:

Name	Type	Default Value	Description
output_path	`Path`	`graph.svg`	File path to the generated Trustable Graph output.
line_length	`int`	`32`	Soft limit on characters-per-line for plotted items.
url	`str`	``	If specified, items have tooltip: `<TEXT>/<DOC>.html#<ITEM>`
same_rank	`list[str]`	`[]`	Fix items on the same vertical rank. Provide as a comma-separated list of item names.
invisible_links	`list[tuple[str, str]]`	`[]`	Add invisible links between items. Links are temporary and used only for visualization. Provide as pairs of item names separated by a space.
pick_levels	`list[tuple[str, str]]`	`[]`	Picks a node and its parents / children recursively to specified levels.
orphan_nodes	`bool`	`False`	Use this argument together with `pick_levels` to retain orphan-nodes and picked nodes.
enable_body_text	`bool`	`True`	Turn on/off item body text rendering.

Tooling

These are options that can be specified to configure how trudag run the various commands.

Name	Type	Default Value	Description
project_name	`str \| None`	`None`	The name for the project in the workspace.
verbose	`bool`	`False`	Enable verbose logging.
workers	`int \| None`	`None`	Set the upperbound for the allowed number of worker threads to spawn when doing parallel tasks. Default: Available software cores.
needs	`bool`	`False`	On/Off to operate on the needs graph.
no-version-print	`bool`	`False`	Disable printing of the tool version when running commands
strict	`bool`	`False`	Enable strict checking of database file (.dotstop.dot), only check implemented is dotfile version against tool version.

Default Configuration

The default configuration options are as follows (version numbers are internally updated):

 configuration version: version-ab0ff9885f96d0461e0b2c7f2ae36c8fa9907308306e55ca1bd963a08955a437

[publish]
output_path = "docs/trustable"

[[publish.reports]]
name = "Software"
include_non_normative = false
score_tables_enable = false
preamble = " Trustable Compliance Report\n\n\n\n### Item status guide ### { .subsection }\n\nEach item in a Trustable Graph is scored with a number between 0 and 1.\nThe score represents aggregated organizational confidence in a given Statement, with larger numbers corresponding to higher confidence.\nScores in the report are indicated by both a numerical score and the colormap below:\n<div class=\"br\" style=\"height: 26px; width: 100%;background: linear-gradient(to right in hsl, hsl(0.0, 100%, 65%) 0%, hsl(120.0, 100%, 30%) 100%);\">\n<span style=\"float:right;\">1.00&nbsp</span>\n<span style=\"float:left;\">&nbsp0.00</span>\n</div>\n\n\nThe status of an item and its links also affect the score.\n\nUnreviewed items are indicated by a cross in the status column.\nThe score of unreviewed items is always set to zero.\n\n\nSuspect links are indicated by a cross in the status column.\nThe contribution to the score of a parent item by a suspiciously linked child is always zero, regardless of the child's own score."

[publish.reports.figures]
enable = false
data_rows_limit = 20

[publish.reports.documents.TA.mappings]
item = "Item"
summary = "Summary"
score = "Score"
score_origin = "Score Origin"
status = "Status"

[publish.reports.documents.TT.mappings]
item = "Item"
summary = "Summary"
score = "Score"
score_origin = "Score Origin"
status = "Status"

[publish.reports.documents.TRUSTABLE.mappings]
item = "Item"
summary = "Summary"
score = "Score"
score_origin = "Score Origin"
status = "Status"

[publish.reports.afterword]
text = ""
include_metadata = true

[artifact.export_options]
path = "Software.json"
name = "Software"
allow_failure = false
include_data_store = false

[artifact.import_options]
path = "Software.json"

[scoring]
enable_validators = true
concurrent_validation = false
scoring_decimal_precision = 5

[scoring.sensitivities]
enable = false
decimal_precision = 5
data_rows_limit = 20

[plot]
output_path = "graph.svg"
line_length = 32
url = ""
same_rank = []
invisible_links = []
pick_levels = []
orphan_nodes = false
enable_body_text = true

[tooling]
verbose = false
needs = false
strict = false