feat: include AdvisoryHead in PurlStatus

[Strum355]

Summary by Sourcery

Include advisory metadata alongside vulnerabilities in PurlStatus and propagate it through the service and API layers.

New Features:

• Expose AdvisoryHead on PurlStatus in the public API to return advisory details with vulnerability status for a purl.

Enhancements:

• Populate PurlStatus.advisory from pre-fetched advisory and issuer data in vulnerability and purl advisory services to avoid additional lookups.

Documentation:

• Document the new advisory field on PurlStatus in the OpenAPI schema.

Tests:

• Extend CSAF and OSV advisory reingest and delete tests to assert the new advisory information on PurlStatus entries.

[sourcery-ai]

Reviewer's Guide

This PR threads AdvisoryHead data into PurlStatus so that each package status now carries its advisory summary, updates the vulnerability service and purl models to construct this enriched status (including issuer lookup), and adjusts tests and the OpenAPI schema to reflect the new field and stabilize comparisons against generated IDs/timestamps.

Sequence diagram for constructing PurlStatus with AdvisoryHead in VulnerabilityService

sequenceDiagram
    participant VS as VulnerabilityService
    participant DB as Connection
    participant AdvMap as advisories_map
    participant Adv as advisory_Model
    participant OrgEnt as organization_Entity
    participant AH as AdvisoryHead
    participant PS as PurlStatus

    VS->>AdvMap: get(advisory_id)
    AdvMap-->>VS: advisory

    VS->>Adv: find_related(organization_Entity)
    Adv->>DB: one(connection)
    DB-->>Adv: issuer_organization
    Adv-->>VS: issuer_organization

    VS->>AH: from_advisory(advisory, Memo::Provided(issuer_organization), connection)
    AH-->>VS: advisory_head

    VS->>PS: from_head(vulnerability_head, advisory_head, status, version_range, cpe, score)
    PS-->>VS: purl_status

    VS->>VS: push purl_status into purl_statuses

Loading

Updated class diagram for PurlStatus including AdvisoryHead

classDiagram
    class PurlStatus {
        +VulnerabilityHead vulnerability
        +AdvisoryHead advisory
        +Severity average_severity
        +f64 average_score
        +String status
        +StatusContext context
        +Option~VersionRange~ version_range
        +Option~String~ cpe
        +async new(vuln_model, advisory_model, status, version_range, cpe, tx) Result~PurlStatus, Error~
        +from_head(vuln_head, advisory_head, status, version_range, cpe, score) Result~PurlStatus, Error~
        +async from_entity(vuln_model, advisory_model, package_status_model, tx) Result~PurlStatus, Error~
    }

    class VulnerabilityHead
    class AdvisoryHead {
        +async from_advisory(advisory_model, issuer_memo, tx) Result~AdvisoryHead, Error~
    }

    class Severity
    class StatusContext
    class VersionRange

    class Memo {
        Provided
        NotProvided
    }

    class vulnerability_model {
    }

    class advisory_model {
    }

    class organization_Entity {
    }

    class purl_status_model {
    }

    PurlStatus --> VulnerabilityHead : contains
    PurlStatus --> AdvisoryHead : contains

    PurlStatus ..> vulnerability_model : uses in new, from_entity
    PurlStatus ..> advisory_model : uses in new, from_entity
    PurlStatus ..> purl_status_model : uses in from_entity

    AdvisoryHead ..> advisory_model : built from
    AdvisoryHead ..> organization_Entity : resolves issuer
    AdvisoryHead ..> Memo : issuer parameter

    PurlStatus ..> Severity : average_severity
    PurlStatus ..> StatusContext : context
    PurlStatus ..> VersionRange : version_range
    PurlStatus ..> Memo : via AdvisoryHead construction

Loading

File-Level Changes

Change	Details	Files
Include AdvisoryHead on PurlStatus and plumb advisory data through construction paths.	Extend PurlStatus model to include an advisory: AdvisoryHead field and update constructors (new, from_head, from_entity) to accept advisory information and compute issuer via organization relations. Update purl advisory aggregation logic to pass advisory models into PurlStatus::from_entity and PurlStatus::new when building status lists. Modify the vulnerability analysis service to accept an advisories_map, resolve advisory models per status row, fetch issuers, and pass AdvisoryHead instances into PurlStatus::from_head and AnalysisAdvisory.	modules/fundamental/src/purl/model/details/purl.rs modules/fundamental/src/vulnerability/service/mod.rs
Adjust tests to assert the new advisory field on PurlStatus while normalizing non-deterministic IDs and timestamps.	Make advisory entries mutable in tests (using &mut and split_at_mut) so that randomly generated advisory UUIDs and issuer IDs can be overwritten with stable values before equality assertions. Update CSAF and OSV reingest and delete tests to populate expected PurlStatus.advisory fields (including issuer, published/modified timestamps, and labels) and to mask runtime-generated UUIDs and, where needed, nanosecond timestamp differences. Ensure adv1/adv2 status assertions in multi-advisory scenarios compare against fully specified PurlStatus structs with the embedded AdvisoryHead.	modules/fundamental/tests/advisory/csaf/reingest.rs modules/fundamental/tests/advisory/osv/reingest.rs modules/fundamental/tests/advisory/csaf/delete.rs
Expose the new advisory field in the public API schema.	Update the OpenAPI schema for PurlStatus to require an advisory property and reference the AdvisoryHead schema, keeping vulnerability and other fields unchanged.	openapi.yaml

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[codecov]

Codecov Report

❌ Patch coverage is 78.94737% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.22%. Comparing base (e224745) to head (c5dd144).

Files with missing lines	Patch %	Lines
modules/fundamental/src/purl/model/details/purl.rs	66.66%	0 Missing and 3 partials ⚠️
...dules/fundamental/src/vulnerability/service/mod.rs	90.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2152      +/-   ##
==========================================
+ Coverage   68.17%   68.22%   +0.04%     
==========================================
  Files         375      375              
  Lines       21052    21067      +15     
  Branches    21052    21067      +15     
==========================================
+ Hits        14353    14372      +19     
+ Misses       5838     5828      -10     
- Partials      861      867       +6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.