Collaboration API¶

API functions for collaboration features.

add_annotation ¶

add_annotation(finding, author, comment, tags=None, status=None)

Add an annotation to a finding.

Parameters:

Name	Type	Description	Default
`finding`	`GhostFinding`	Finding to annotate.	required
`author`	`str`	Name of the person creating the annotation.	required
`comment`	`str`	Comment text.	required
`tags`	`list[str] \| None`	Optional list of tags.	`None`
`status`	`str \| None`	Optional status update ("reviewed", "fixed", "false_positive").	`None`

Returns:

Type	Description
`Annotation`	Created Annotation instance.

Source code in lavendertown/collaboration/api.py

def add_annotation(
    finding: GhostFinding,
    author: str,
    comment: str,
    tags: list[str] | None = None,
    status: str | None = None,
) -> Annotation:
    """Add an annotation to a finding.

    Args:
        finding: Finding to annotate.
        author: Name of the person creating the annotation.
        comment: Comment text.
        tags: Optional list of tags.
        status: Optional status update ("reviewed", "fixed", "false_positive").

    Returns:
        Created Annotation instance.
    """
    finding_id = get_finding_id(finding)

    annotation = Annotation(
        id=str(uuid.uuid4()),
        finding_id=finding_id,
        author=author,
        timestamp=datetime.now(),
        comment=comment,
        tags=tags or [],
        status=status,
    )

    save_annotation(annotation)
    return annotation

get_annotations ¶

get_annotations(finding)

Get all annotations for a finding.

Parameters:

Name	Type	Description	Default
`finding`	`GhostFinding`	Finding to get annotations for.	required

Returns:

Type	Description
`list[Annotation]`	List of Annotation objects for the finding.

Source code in lavendertown/collaboration/api.py

def get_annotations(finding: GhostFinding) -> list[Annotation]:
    """Get all annotations for a finding.

    Args:
        finding: Finding to get annotations for.

    Returns:
        List of Annotation objects for the finding.
    """
    finding_id = get_finding_id(finding)
    return load_annotations(finding_id)

create_shareable_report ¶

create_shareable_report(
    title, author, findings, annotations=None, ruleset=None, metadata=None
)

Create a shareable report.

Parameters:

Name	Type	Description	Default
`title`	`str`	Report title.	required
`author`	`str`	Name of the person creating the report.	required
`findings`	`list[GhostFinding]`	List of findings to include.	required
`annotations`	`list[Annotation] \| None`	Optional list of annotations to include.	`None`
`ruleset`	`RuleSet \| None`	Optional ruleset used for analysis.	`None`
`metadata`	`dict[str, Any] \| None`	Optional additional metadata.	`None`

Returns:

Type	Description
`ShareableReport`	Created ShareableReport instance.

Source code in lavendertown/collaboration/api.py

def create_shareable_report(
    title: str,
    author: str,
    findings: list[GhostFinding],
    annotations: list[Annotation] | None = None,
    ruleset: RuleSet | None = None,
    metadata: dict[str, Any] | None = None,
) -> ShareableReport:
    """Create a shareable report.

    Args:
        title: Report title.
        author: Name of the person creating the report.
        findings: List of findings to include.
        annotations: Optional list of annotations to include.
        ruleset: Optional ruleset used for analysis.
        metadata: Optional additional metadata.

    Returns:
        Created ShareableReport instance.
    """
    import uuid

    report = ShareableReport(
        id=str(uuid.uuid4()),
        title=title,
        author=author,
        created_at=datetime.now(),
        findings=findings,
        annotations=annotations or [],
        ruleset=ruleset,
        metadata=metadata or {},
    )

    return report

export_report ¶

export_report(report, filepath=None)

Export a shareable report to a file.

Parameters:

Name	Type	Description	Default
`report`	`ShareableReport`	Report to export.	required
`filepath`	`str \| None`	Optional path to save the report. If None, saves to default reports directory.	`None`

Returns:

Type	Description
`Path`	Path where the report was saved.

Source code in lavendertown/collaboration/api.py

def export_report(report: ShareableReport, filepath: str | None = None) -> Path:
    """Export a shareable report to a file.

    Args:
        report: Report to export.
        filepath: Optional path to save the report. If None, saves to
            default reports directory.

    Returns:
        Path where the report was saved.
    """
    return save_report(report, filepath)

import_report ¶

import_report(filepath)

Import a shareable report from a file.

Parameters:

Name	Type	Description	Default
`filepath`	`str`	Path to the report JSON file.	required

Returns:

Type	Description
`ShareableReport`	ShareableReport instance loaded from the file.

Source code in lavendertown/collaboration/api.py

def import_report(filepath: str) -> ShareableReport:
    """Import a shareable report from a file.

    Args:
        filepath: Path to the report JSON file.

    Returns:
        ShareableReport instance loaded from the file.
    """
    return load_report(filepath)