stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
b8b2d83f4a86d42c4a35507958393002ecbd85cf
git.stella-ops.org/src/Concelier/__Libraries/StellaOps.Concelier.Connector.Osv/AGENTS.md
master 3a2100aa78 Add unit and integration tests for VexCandidateEmitter and SmartDiff repositories 
- Implemented comprehensive unit tests for VexCandidateEmitter to validate candidate emission logic based on various scenarios including absent and present APIs, confidence thresholds, and rate limiting.
- Added integration tests for SmartDiff PostgreSQL repositories, covering snapshot storage and retrieval, candidate storage, and material risk change handling.
- Ensured tests validate correct behavior for storing, retrieving, and querying snapshots and candidates, including edge cases and expected outcomes.
2025-12-16 19:00:43 +02:00

2.6 KiB
Raw Blame History

AGENTS

Role

Connector for OSV.dev across ecosystems; authoritative SemVer/PURL ranges for OSS packages.

Scope

  • Fetch by ecosystem or time range; handle pagination and changed-since cursors.
  • Parse OSV JSON; validate schema; capture introduced/fixed events, database_specific where relevant.
  • Map to Advisory with AffectedPackage(type=semver, Identifier=PURL); preserve SemVer constraints and introduced/fixed chronology.
  • Maintain per-ecosystem cursors and deduplicate runs via payload hashes to keep reruns idempotent.

Participants

  • Source.Common supplies HTTP clients, pagination helpers, and validators.
  • Storage.Postgres persists documents, DTOs, advisories, and source_state cursors.
  • Merge engine resolves OSV vs GHSA consistency; prefers SemVer data for libraries; distro OVAL still overrides OS packages.
  • Exporters serialize per-ecosystem ranges untouched.

Interfaces & contracts

  • Job kinds: osv:fetch, osv:parse, osv:map (naming consistent with other connectors).
  • Aliases include CVE/GHSA/OSV IDs; references include advisory/patch/release URLs.
  • Provenance records method=parser and source=osv.

In/Out of scope

In: SemVer+PURL accuracy for OSS ecosystems. Out: vendor PSIRT and distro OVAL specifics.

Observability & security expectations

  • Metrics: SourceDiagnostics exposes the shared concelier.source.http.* counters/histograms tagged concelier.source=osv; observability dashboards slice on the tag to monitor item volume, schema failures, range counts, and ecosystem coverage. Logs include ecosystem and cursor values.

Tests

  • Author and review coverage in ../StellaOps.Concelier.Connector.Osv.Tests.
  • Shared fixtures (e.g., PostgresIntegrationFixture, ConnectorTestHarness) live in ../StellaOps.Concelier.Testing.
  • Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.

Required Reading

  • docs/modules/concelier/architecture.md
  • docs/modules/platform/architecture-overview.md

Working Agreement

    1. Update task status to DOING/DONE in both correspoding sprint file /docs/implplan/SPRINT_*.md and the local TASKS.md when you start or finish work.
    1. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
    1. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
    1. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
    1. Revert to TODO if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.