trudag.manage

Additional functionality required by but not specific to the CLI.

add_item

add_item(
    current_graph: TrustableGraph,
    dotstop_path: Path,
    filepath: Path,
    parent: str,
)

Takes the markdown file at :filepath: and adds it to the graph with :prefix: and :id:. If :parent: is provided the item is linked appropriately.

Parameters:

Name	Type	Description	Default
`current_graph`	`TrustableGraph`	the current trustable graph	required
`dotstop_path`	`Path`	the path to the projects dotstop file	required
`filepath`	`Path`	the path to the new items .md file	required
`parent`	`str`	the parent item of the new item. Can be set to "" to create an orphaned node.	required

Raises:

Type	Description
`GraphActionError`	If the item already exists in the current graph.
`FileNotFoundError`	If the file path does not contain a markdown file.
`ItemError`	If the markdown at :filepath: is malformatted

create_new_item

create_new_item(
    prefix: str,
    path: Path,
    parent: str,
    uid: str,
    output_file: Path,
    dot_graph: TrustableGraph,
    existing_file: bool = False,
) -> None

Create a new Item in the filesystem and add it to dot_graph.

Updates dot_graph and writes it as dot to output_file. Creates a default item file at f"{path}/{prefix}-{name}.md".

Parameters:

Name	Type	Description	Default
`prefix`	`str`	Document prefix for the new item	required
`path`	`Path`	Directory where new item will be written.	required
`parent`	`str`	Name of the parent item, if any.	required
`uid`	`str`	Unique (within a document) name for the item.	required
`output_file`	`Path`	File to write the updated graph to.	required
`dot_graph`	`TrustableGraph`	Graph to update and write to file.	required
`existing_file`	`bool`	When True use a pre-existing markdown file.	`False`

Raises:

Type	Description
`GraphActionError`	If the item to create contains a reserved character.
`FileExistsError`	If the file path for the item to create is not a valid directory.

describe_item

describe_item(
    graph: TrustableGraph, item_name: str, statement: bool
) -> str

Describes item and formats item details as a human-readable output.

Parameters:

Name	Type	Description	Default
`graph`	`TrustableGraph`	Graph to use for describing the item	required
`item_name`	`str`	Item name to be described	required
`statement`	`bool`	If statement of the item should be included in the output	required

diff_graph_git

diff_graph_git(
    current_graph: TrustableGraph, revision: str
) -> ExitCodes

Compare the current graph with the version of the graph in a given Git branch.

Parameters:

Name	Type	Description	Default
`current_graph`	`TrustableGraph`	The current trustable graph.	required
`revision`	`str`	Git revision to compare against.	required

Returns:

Name	Type	Description
`ExitCodes`	`ExitCodes`	SUCCESS if no changed SME items are detected, else SME_ITEM_CHANGE_DETECTED.

Raises:

Type	Description
`GitError`	If the specified branch cannot be found or compared.

Notes

Logs removed and added items.
Logs content differences for changed items.
Logs SME scores for changed items if available.

diff_lint_report

diff_lint_report(
    lint_report_old_path: Path, lint_report_new_path: Path
) -> ExitCodes

Compare two lint reports and log differences.

Parameters:

Name	Type	Description	Default
`lint_report_old_path`	`Path`	Path to the old lint report.	required
`lint_report_new_path`	`Path`	Path to the new lint report.	required

Returns:

Name	Type	Description
`ExitCodes`	`ExitCodes`	SUCCESS if reports match; otherwise, a LINT_FAILURE.

Raises:

Type	Description
`TypeError`	If reports cannot be loaded or parsed.

lint

lint(graph: TrustableGraph, dump: Path | None) -> ExitCodes

Perform linting on the graph and log warnings for any issues found.

Parameters:

Name	Type	Description	Default
`graph`	`TrustableGraph`	The graph to lint.	required
`dump`	`Path \| None`	Dumps the result into a specified path. Extension determines the format of the dump. Allowed extensions: .json	required

Returns:

Name	Type	Description
`ExitCodes`	`ExitCodes`	LINT_FAILURE if issues are found, SUCCESS otherwise.

lint_diff

lint_diff(
    current_graph: TrustableGraph,
    compare_branch: str,
    workers: int | None,
) -> ExitCodes

Compare the current graph against another git branch's graph and log differences.

Logs

New or removed unreviewed items
New or removed suspect links
Items with changed SHAs
Changed items with associated SME scores

Warning

This function checks out the target git branch temporarily, and restores HEAD afterward.

Parameters:

Name	Type	Description	Default
`current_graph`	`TrustableGraph`	The current working graph.	required
`compare_branch`	`str`	The git branch to compare against.	required
`workers`	`int \| None`	The upperbound for worker threads to spawn.	required

Returns:

Name	Type	Description
`ExitCodes`	`ExitCodes`	LINT_FAILURE if any differences are found, SUCCESS otherwise.

move_item

move_item(
    source_graph: TrustableGraph,
    source_dotstop: Path,
    dest_graph: TrustableGraph,
    dest_dotstop: Path,
    items: tuple[str, ...],
)

Move item(s) from one graph to another (e.g. needs to dotstop or vice versa).

The item must have no links (parents or children) in the source graph. The markdown file is not moved or deleted.

Parameters:

Name	Type	Description	Default
`source_graph`	`TrustableGraph`	the graph to move items from	required
`source_dotstop`	`Path`	the path to the source dotstop file	required
`dest_graph`	`TrustableGraph`	the graph to move items to	required
`dest_dotstop`	`Path`	the path to the destination dotstop file	required
`items`	`tuple[str, ...]`	names of items to move	required

Raises:

Type	Description
`GraphActionError`	If an item doesn't exist, already exists in destination, or has links in the source graph.

remove_item

remove_item(
    current_graph: TrustableGraph,
    dotstop_path: Path,
    items: tuple[str, ...],
    delete_file: bool = True,
)

Remove item(s) from the graph and optionally delete their markdown files.

Parameters:

Name	Type	Description	Default
`current_graph`	`TrustableGraph`	the current trustable graph	required
`dotstop_path`	`Path`	the path to the projects dotstop file	required
`work_dir`	`Path`	the working directory	required
`items`	`tuple[str, ...]`	names of items to remove	required
`delete_file`	`bool`	if true, delete item markdown files	`True`

Raises:

Type	Description
`GraphActionError`	If an item doesn't exist in the current graph.

rename_item

rename_item(
    current_graph: TrustableGraph,
    dotstop_path: Path,
    name_from: str,
    prefix: str | None = None,
    identifier: str | None = None,
    delete_file: bool = True,
)

Takes the item :name_from: and renames it with a new :prefix: or :id: this involves copying the .md file to a new name, and updating the dotstop with new links and item and removing the old links and item. The old .md file is not removed.

Parameters:

Name	Type	Description	Default
`current_graph`	`TrustableGraph`	the current trustable graph	required
`dotstop_path`	`Path`	the path to the projects dotstop file	required
`name_from`	`str`	the name of the item to move	required
`prefix`	`str`	the new prefix to move the item to	`None`
`identifier`	`str`	the new id for the item (optional) if no value is provided it will use the id from name_from	`None`
`delete_file`	`bool`	delete file for item with old name	`True`

Raises:

Type	Description
`GraphActionError`	If the item to rename doesn't exist in the current graph.
`FileExistsError`	If the file path for the item to rename is not a valid directory.

set_all_link_status

set_all_link_status(
    current_graph: TrustableGraph,
    item: str,
    status: LinkStatus,
) -> None

This sets the link status of all links from the item as status. This will not change the link status of links to items that aren't reviewed.

Parameters:

Name	Type	Description	Default
`current_graph`	`TrustableGraph`	The current working graph.	required
`item`	`str`	The item to set all the links from/to.	required
`status`	`LinkStatus`	The status to set the links to	required