projectuc

package
v0.1.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 15, 2026 License: Apache-2.0 Imports: 33 Imported by: 0

Documentation

Overview

Package projectuc implements project application logic.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ValidateCursorSecret

func ValidateCursorSecret(key []byte) error

ValidateCursorSecret returns an error when key is nil or shorter than 32 bytes.

Types

type AnalysisMetadata

type AnalysisMetadata struct {
	ID           string    `json:"id"`
	CreatedAt    time.Time `json:"created_at"`
	SourceRef    string    `json:"source_ref,omitempty"`
	SourceCommit string    `json:"source_commit,omitempty"`
}

AnalysisMetadata provides contextual information about the analysis snapshot.

type ChildCollection

type ChildCollection struct {
	Items      []MeasureNode `json:"items"`
	NextCursor *string       `json:"next_cursor"`
}

ChildCollection wraps a paginated list of immediate child nodes.

type CodeDiffView added in v0.1.8

type CodeDiffView struct {
	AnalysisID       string                     `json:"analysis_id"`
	Base             *CodeRevision              `json:"base,omitempty"`
	Head             CodeRevision               `json:"head"`
	Path             string                     `json:"path"`
	View             string                     `json:"view"`
	ContextTruncated bool                       `json:"context_truncated"`
	Change           projectanalysis.FileChange `json:"change"`
	BaseFile         projectanalysis.SourceFile `json:"base_file,omitempty"`
	SourceFile       projectanalysis.SourceFile `json:"source_file,omitempty"`
}

type CodeFile added in v0.1.8

type CodeFile struct {
	Path             string                            `json:"path"`
	OldPath          string                            `json:"old_path,omitempty"`
	Status           string                            `json:"status"`
	Language         string                            `json:"language,omitempty"`
	Lines            int                               `json:"lines"`
	FindingCount     int                               `json:"finding_count"`
	ChangedLineCount int                               `json:"changed_line_count"`
	Binary           bool                              `json:"binary"`
	Generated        bool                              `json:"generated"`
	SourceAvailable  bool                              `json:"source_available"`
	SourceReason     projectanalysis.UnavailableReason `json:"source_reason,omitempty"`
}

type CodeFileFilter added in v0.1.8

type CodeFileFilter struct {
	IncludeGenerated bool
	Changed          *bool
	HasFindings      *bool
	Prefix           string
	Status           string
}

type CodeFileView added in v0.1.8

type CodeFileView struct {
	AnalysisID            string        `json:"analysis_id"`
	Base                  *CodeRevision `json:"base,omitempty"`
	Head                  CodeRevision  `json:"head"`
	File                  CodeFile      `json:"file"`
	FromLine              int           `json:"from_line"`
	ToLine                int           `json:"to_line"`
	TotalLines            int           `json:"total_lines"`
	Lines                 []CodeLine    `json:"lines"`
	Findings              []CodeFinding `json:"findings"`
	LineCoverageAvailable bool          `json:"-"`
}

type CodeFinding added in v0.1.8

type CodeFinding struct {
	ID              string                 `json:"id"`
	Kind            string                 `json:"kind"`
	RuleKey         string                 `json:"rule_key,omitempty"`
	RuleName        string                 `json:"rule_name,omitempty"`
	Type            string                 `json:"type,omitempty"`
	Severity        shared.Severity        `json:"severity"`
	DetectionStatus finding.Status         `json:"detection_status"`
	CurrentStatus   string                 `json:"current_status,omitempty"`
	Message         string                 `json:"message,omitempty"`
	Location        finding.SourceLocation `json:"location"`
	New             bool                   `json:"new"`
}

CodeFinding is the display-safe immutable finding marker for a source response. DetectionStatus is immutable; CurrentStatus is optional mutable triage state.

type CodeLine added in v0.1.8

type CodeLine struct {
	Number     int     `json:"number"`
	Content    string  `json:"content"`
	Change     string  `json:"change"`
	Duplicated bool    `json:"duplicated"`
	Coverage   *string `json:"coverage"`
}

type CodeLineOverlay added in v0.1.8

type CodeLineOverlay struct {
	Line       int   `json:"line"`
	Covered    *bool `json:"covered,omitempty"`
	Changed    bool  `json:"changed,omitempty"`
	Duplicated bool  `json:"duplicated,omitempty"`
}

CodeLineOverlay is sparse: a nil coverage value means unknown/not executable.

type CodeRevision added in v0.1.8

type CodeRevision struct {
	Ref            string `json:"ref,omitempty"`
	Commit         string `json:"commit,omitempty"`
	ArtifactDigest string `json:"artifact_digest,omitempty"`
}

type ComplexityMeasures

type ComplexityMeasures struct {
	Cyclomatic MeasureCountMetric `json:"cyclomatic"`
	Cognitive  MeasureCountMetric `json:"cognitive"`
}

ComplexityMeasures encapsulates structural complexity metrics.

type CountMetric

type CountMetric struct {
	Availability      MetricAvailability
	Value             *int
	UnavailableReason *UnavailableReason
}

type CoverageMeasures

type CoverageMeasures struct {
	CoveredLines    MeasureCountMetric   `json:"covered_lines"`
	CoverableLines  MeasureCountMetric   `json:"coverable_lines"`
	Coverage        MeasureDecimalMetric `json:"coverage"`
	NewCodeCoverage MeasureDecimalMetric `json:"new_code_coverage"`
}

CoverageMeasures encapsulates code coverage metrics.

type CreateInput

type CreateInput struct {
	TenantID             shared.ID
	CreatedBy            string
	Name                 string
	Key                  string
	SourceBinding        project.SourceBinding
	DefaultProfileByLang map[string]string
	GateID               string
}

type DebtMeasures

type DebtMeasures struct {
	RemediationEffortMinutes MeasureCountMetric `json:"remediation_effort_minutes"`
}

DebtMeasures encapsulates technical debt metrics.

type DuplicationMeasures

type DuplicationMeasures struct {
	DuplicatedLines    MeasureCountMetric   `json:"duplicated_lines"`
	DuplicationBlocks  MeasureCountMetric   `json:"duplication_blocks"`
	DuplicationDensity MeasureDecimalMetric `json:"duplication_density"`
}

DuplicationMeasures encapsulates source code duplication metrics.

type IssueMeasures

type IssueMeasures struct {
	ByType     map[string]MeasureCountMetric `json:"by_type"`
	BySeverity map[string]MeasureCountMetric `json:"by_severity"`
}

IssueMeasures encapsulates finding counts broken down by type and severity.

type LatestAnalysis

type LatestAnalysis struct {
	Analysis projectanalysis.Analysis
	Result   []byte
}

type MeasureAvailabilityState

type MeasureAvailabilityState string

MeasureAvailabilityState describes whether a measure has a meaningful value.

const (
	// AvailabilityAvailable indicates the measure value is present and valid.
	AvailabilityAvailable MeasureAvailabilityState = "available"
	// AvailabilityUnavailable indicates the measure value could not be computed.
	AvailabilityUnavailable MeasureAvailabilityState = "unavailable"
	// AvailabilityNotApplicable indicates the measure does not apply to this node type.
	AvailabilityNotApplicable MeasureAvailabilityState = "not_applicable"
)

type MeasureCountMetric

type MeasureCountMetric struct {
	Availability MeasureAvailabilityState `json:"availability"`
	Value        *int                     `json:"value"`
	Reason       *string                  `json:"unavailable_reason"`
}

MeasureCountMetric represents an integer measure and its availability state.

type MeasureCursor

type MeasureCursor struct {
	Version       int    `json:"v"`
	AnalysisID    string `json:"a"`
	Path          string `json:"r"`
	LastKindRank  int    `json:"k"`
	LastChildPath string `json:"l"`
}

MeasureCursor is the opaque pagination token used to iterate through children.

func DecodeMeasureCursor

func DecodeMeasureCursor(s string, secret []byte) (*MeasureCursor, error)

DecodeMeasureCursor decodes, verifies the signature, and validates the integrity of a pagination cursor.

func (*MeasureCursor) Encode

func (c *MeasureCursor) Encode(secret []byte) string

Encode serializes the cursor and cryptographically signs it to prevent tampering.

type MeasureDecimalMetric

type MeasureDecimalMetric struct {
	Availability MeasureAvailabilityState `json:"availability"`
	Value        *float64                 `json:"value"`
	Reason       *string                  `json:"unavailable_reason"`
}

MeasureDecimalMetric represents a floating-point measure and its availability state.

type MeasureGradeMetric

type MeasureGradeMetric struct {
	Availability MeasureAvailabilityState `json:"availability"`
	Grade        *string                  `json:"grade"`
	Reason       *string                  `json:"unavailable_reason"`
}

MeasureGradeMetric represents a letter grade (e.g., A, B, C) and its availability state.

type MeasureNode

type MeasureNode struct {
	Path        string               `json:"path"`
	Name        string               `json:"name"`
	Kind        measure.NodeKind     `json:"kind"`
	Language    string               `json:"language,omitempty"`
	Size        *SizeMeasures        `json:"size,omitempty"`
	Complexity  *ComplexityMeasures  `json:"complexity,omitempty"`
	Coverage    *CoverageMeasures    `json:"coverage,omitempty"`
	Duplication *DuplicationMeasures `json:"duplication,omitempty"`
	Issues      *IssueMeasures       `json:"issues,omitempty"`
	Debt        *DebtMeasures        `json:"debt,omitempty"`
	Ratings     *RatingsMeasures     `json:"ratings,omitempty"`
}

MeasureNode represents a single directory, file, or project root with its computed measures.

type MetricAvailability

type MetricAvailability string
const (
	MetricAvailable     MetricAvailability = "available"
	MetricUnavailable   MetricAvailability = "unavailable"
	MetricNotSupplied   MetricAvailability = "not_supplied"
	MetricNotApplicable MetricAvailability = "not_applicable"
)

type Overview

type Overview struct {
	State          OverviewState
	Project        OverviewProject
	LatestAnalysis *OverviewAnalysis
	Gate           *OverviewGate
	IssueSummary   OverviewIssueSummary
	Overall        OverviewLens
	NewCode        OverviewLens
}

type OverviewAnalysis

type OverviewAnalysis struct {
	ID           string
	CreatedAt    time.Time
	SourceRef    string
	SourceCommit string
	NewCode      OverviewNewCodePeriod
}

type OverviewGate

type OverviewGate struct {
	Status           OverviewGateStatus
	Key              *string
	Name             *string
	Source           *OverviewGateSource
	FailedConditions []OverviewGateCondition
}

type OverviewGateCondition

type OverviewGateCondition struct {
	Metric    string
	Operator  OverviewGateOperator
	Threshold float64
	Actual    float64
}

type OverviewGateOperator

type OverviewGateOperator string
const (
	OverviewGateOperatorLE OverviewGateOperator = "<="
	OverviewGateOperatorGE OverviewGateOperator = ">="
	OverviewGateOperatorEQ OverviewGateOperator = "=="
	OverviewGateOperatorLT OverviewGateOperator = "<"
	OverviewGateOperatorGT OverviewGateOperator = ">"
)

type OverviewGateSource

type OverviewGateSource string
const (
	OverviewGateSourceDefault    OverviewGateSource = "default"
	OverviewGateSourceRepository OverviewGateSource = "repository"
	OverviewGateSourceManaged    OverviewGateSource = "managed"
)

type OverviewGateStatus

type OverviewGateStatus string
const (
	OverviewGatePassed     OverviewGateStatus = "passed"
	OverviewGateFailed     OverviewGateStatus = "failed"
	OverviewGateIncomplete OverviewGateStatus = "incomplete"
)

type OverviewGrade

type OverviewGrade string
const (
	OverviewGradeA OverviewGrade = "A"
	OverviewGradeB OverviewGrade = "B"
	OverviewGradeC OverviewGrade = "C"
	OverviewGradeD OverviewGrade = "D"
	OverviewGradeE OverviewGrade = "E"
)

type OverviewIssueSummary

type OverviewIssueSummary struct {
	NewCodeTotal         CountMetric
	AcceptedOverallTotal CountMetric
}

type OverviewLens

type OverviewLens struct {
	Security                 RatingMetric
	Reliability              RatingMetric
	Maintainability          RatingMetric
	SecurityHotspotsReviewed PercentageMetric
	Coverage                 PercentageMetric
	Duplications             PercentageMetric
}

type OverviewNewCodePeriod

type OverviewNewCodePeriod struct {
	FirstAnalysis      bool
	HasBaseline        bool
	BaselineAnalysisID *string
}

type OverviewProject

type OverviewProject struct {
	Key  string
	Name string
}

type OverviewState

type OverviewState string
const (
	OverviewStateNotAnalyzed OverviewState = "not_analyzed"
	OverviewStateAnalyzed    OverviewState = "analyzed"
)

type PercentageMetric

type PercentageMetric struct {
	Availability      MetricAvailability
	Value             *float64
	Grade             *OverviewGrade
	UnavailableReason *UnavailableReason
}

type ProjectMeasureResponse

type ProjectMeasureResponse struct {
	State           string            `json:"state"` // "analyzed", "not_analyzed"
	Project         ProjectNodeInfo   `json:"project"`
	Analysis        *AnalysisMetadata `json:"analysis"`
	Path            string            `json:"path"`
	IncludedDomains []string          `json:"included_domains"`
	Node            *MeasureNode      `json:"node"`
	Children        ChildCollection   `json:"children"`
}

ProjectMeasureResponse is the root response payload for the measures API endpoint.

type ProjectNodeInfo

type ProjectNodeInfo struct {
	Key  string `json:"key"`
	Name string `json:"name"`
}

ProjectNodeInfo provides basic identifying information about the project.

type ProjectSummary

type ProjectSummary struct {
	Project        *project.Project
	LatestAnalysis *projectanalysis.Analysis
	LatestJob      *ports.ScanJob
}

ProjectSummary combines a Project with its latest decision record and active job.

type PublishSourceInput added in v0.1.8

type PublishSourceInput struct {
	TenantID    shared.ID
	ProjectKey  string
	AnalysisID  string
	Actor       string
	ToolVersion string
	Archive     io.Reader
}

PublishSourceInput contains only contributor-controlled facts that are safe to accept. Tenant and project identity are resolved by the authenticated server path, never from the archive.

type RatingMetric

type RatingMetric struct {
	Availability      MetricAvailability
	Grade             *OverviewGrade
	UnavailableReason *UnavailableReason
}

type RatingsMeasures

type RatingsMeasures struct {
	Security        MeasureGradeMetric `json:"security"`
	Reliability     MeasureGradeMetric `json:"reliability"`
	Maintainability MeasureGradeMetric `json:"maintainability"`
}

RatingsMeasures encapsulates high-level grades for security, reliability, and maintainability.

type Service

type Service struct {
	// contains filtered or unexported fields
}

func NewService

func NewService(repo ports.ProjectRepository, engagements ports.EngagementRepository, clock ports.Clock, ids ports.IDGenerator, audit ports.AuditLogger, allowLocalSource bool) *Service

func (*Service) AnalysisStatus

func (s *Service) AnalysisStatus(ctx context.Context, tenantID shared.ID, key string) (ports.ScanJob, error)

func (*Service) AssignGate

func (s *Service) AssignGate(ctx context.Context, actor string, tenantID shared.ID, key, gateID string) (*project.Project, error)

func (*Service) Create

func (s *Service) Create(ctx context.Context, in CreateInput) (*project.Project, error)

func (*Service) CreateFromArchive

func (s *Service) CreateFromArchive(ctx context.Context, in CreateInput, filename string, src io.Reader) (*project.Project, error)

func (*Service) Delete

func (s *Service) Delete(ctx context.Context, actor string, tenantID shared.ID, key string) error

func (*Service) Get

func (s *Service) Get(ctx context.Context, tenantID shared.ID, key string) (*project.Project, error)

func (*Service) GetAnalysis

func (s *Service) GetAnalysis(ctx context.Context, tenantID shared.ID, key, id string) (projectanalysis.Analysis, error)

GetAnalysis returns one snapshot without disclosing another Project's history.

func (*Service) GetHotspot

func (s *Service) GetHotspot(ctx context.Context, tenantID shared.ID, key string, hotspotID shared.ID) (hotspot.Hotspot, error)

GetHotspot returns one projection only after the Project has been resolved in the caller's tenant.

func (*Service) GetIssue

func (s *Service) GetIssue(ctx context.Context, tenantID shared.ID, key string, issueID shared.ID) (issue.Issue, error)

GetIssue returns one issue only after the Project is resolved in the caller's tenant.

func (*Service) GetMeasures

func (s *Service) GetMeasures(ctx context.Context, tenantID, projectKey, path string, domains []string, limit int, cursorStr string) (ProjectMeasureResponse, error)

GetMeasures retrieves the measure node and its direct children for a specific path.

func (*Service) HotspotHistory

func (s *Service) HotspotHistory(ctx context.Context, tenantID shared.ID, key string, hotspotID shared.ID) ([]hotspot.ReviewEvent, error)

HotspotHistory returns the immutable review event history of a hotspot.

func (*Service) IssueHistory

func (s *Service) IssueHistory(ctx context.Context, tenantID shared.ID, key string, issueID shared.ID) ([]issue.ReviewEvent, error)

IssueHistory returns the immutable, append-only lifecycle history of an issue.

func (*Service) LatestAnalysis

func (s *Service) LatestAnalysis(ctx context.Context, tenantID shared.ID, key string) (LatestAnalysis, error)

func (*Service) List

func (s *Service) List(ctx context.Context, tenantID shared.ID) ([]*project.Project, error)

func (*Service) ListAnalyses

func (s *Service) ListAnalyses(ctx context.Context, tenantID shared.ID, key string, limit int, beforeCreatedAt time.Time, beforeID shared.ID) ([]projectanalysis.Analysis, bool, error)

ListAnalyses returns one immutable Project history page, newest first.

func (*Service) ListCodeFiles added in v0.1.8

func (s *Service) ListCodeFiles(ctx context.Context, tenantID shared.ID, key, analysisID string) ([]CodeFile, projectanalysis.SourceCapabilities, error)

ListCodeFiles returns the immutable snapshot inventory enriched with retained-source state.

func (*Service) ListCodeFilesWithFilter added in v0.1.8

func (s *Service) ListCodeFilesWithFilter(ctx context.Context, tenantID shared.ID, key, analysisID string, filter CodeFileFilter) ([]CodeFile, projectanalysis.SourceCapabilities, error)

ListCodeFilesWithFilter derives the inventory only from persisted analysis metadata.

func (*Service) ListHotspots

func (s *Service) ListHotspots(ctx context.Context, tenantID shared.ID, key string, filter hotspot.ListFilter) (hotspot.Page, error)

ListHotspots returns projections belonging to the requested tenant and Project for the current analysis lens.

func (*Service) ListIssues

func (s *Service) ListIssues(ctx context.Context, tenantID shared.ID, key string, filter issue.ListFilter) (issue.Page, error)

ListIssues returns the tenant- and Project-scoped code-quality issues for the faceted explorer. Cross-tenant/unknown projects resolve to not-found via Get.

func (*Service) ListSummaries

func (s *Service) ListSummaries(ctx context.Context, tenantID shared.ID) ([]ProjectSummary, error)

ListSummaries serves the unpaginated Project portfolio without browser-side N+1 requests. add cursor pagination plus server-side filters when returning a tenant's full searchable portfolio becomes materially expensive.

func (*Service) Overview

func (s *Service) Overview(ctx context.Context, tenantID shared.ID, key string) (Overview, error)

func (*Service) PublishSource added in v0.1.8

PublishSource contributes source bytes to an already-created server-owned analysis. It never creates an analysis and never lets the caller choose an artifact namespace.

func (*Service) ReadCodeDiff added in v0.1.8

func (s *Service) ReadCodeDiff(ctx context.Context, tenantID shared.ID, key, analysisID, path, view string, contextLines int) (CodeDiffView, projectanalysis.SourceCapabilities, error)

ReadCodeDiff serves scan-time persisted hunk data. Git is never called from this read path.

func (*Service) ReadCodeFile added in v0.1.8

func (s *Service) ReadCodeFile(ctx context.Context, tenantID shared.ID, key, analysisID, path string, fromLine, toLine int) (CodeFileView, projectanalysis.SourceCapabilities, error)

ReadCodeFile resolves exact analysis ownership before reading one bounded source window.

func (*Service) RecordProjectAnalysis

func (s *Service) RecordProjectAnalysis(ctx context.Context, engagementID shared.ID, jobID string, completedAt time.Time, result *scauc.ScanResult) (recordErr error)

RecordProjectAnalysis is called by SCA only after a successful pipeline and before its ScanJob becomes succeeded. Non-Project scans intentionally no-op.

func (*Service) SetAnalysisStore

func (s *Service) SetAnalysisStore(store ports.ProjectAnalysisStore)

func (*Service) SetArchiveStore

func (s *Service) SetArchiveStore(store ports.ProjectArchiveStore)

func (*Service) SetCursorSecret

func (s *Service) SetCursorSecret(secret []byte) error

SetCursorSecret injects the HMAC signing key for pagination cursors. Returns an error when the key is absent or shorter than 32 bytes. The byte slice is copied so later caller mutation cannot alter the service key.

func (*Service) SetFindingRepository

func (s *Service) SetFindingRepository(repo ports.FindingRepository)

func (*Service) SetHotspotStore

func (s *Service) SetHotspotStore(store ports.ProjectHotspotStore)

func (*Service) SetIssueStore

func (s *Service) SetIssueStore(store ports.ProjectIssueStore)

func (*Service) SetProjectAnalysisCompletionTimeout added in v0.1.8

func (s *Service) SetProjectAnalysisCompletionTimeout(timeout time.Duration)

func (*Service) SetQualityGateMutator

func (s *Service) SetQualityGateMutator(mutator ports.QualityGateMutator)

func (*Service) SetQualityGates

func (s *Service) SetQualityGates(gates *qualitygatesuc.Service)

func (*Service) SetQualityProfiles

func (s *Service) SetQualityProfiles(profiles *qualityprofilesuc.Service)

func (*Service) SetRuleCatalog

func (s *Service) SetRuleCatalog(catalog ports.RuleCatalog)

func (*Service) SetScanner

func (s *Service) SetScanner(scanner *scauc.Service)

func (*Service) SetSourceArtifactStore added in v0.1.8

func (s *Service) SetSourceArtifactStore(store ports.ProjectSourceArtifactStore)

func (*Service) StartAnalysis

func (s *Service) StartAnalysis(ctx context.Context, actor string, tenantID shared.ID, key string, coverage *measure.CoverageReport) (ports.ScanJob, error)

func (*Service) TransitionHotspot

func (s *Service) TransitionHotspot(ctx context.Context, actor string, tenantID shared.ID, key string, hotspotID shared.ID, to hotspot.Status, rationale string, expectedVersion int) (hotspot.Hotspot, hotspot.ReviewEvent, error)

TransitionHotspot applies a human review decision to a hotspot.

func (*Service) TransitionIssue

func (s *Service) TransitionIssue(ctx context.Context, actor string, tenantID shared.ID, key string, issueID shared.ID, to issue.Status, rationale string, expectedVersion int) (issue.Issue, issue.ReviewEvent, error)

TransitionIssue applies an attributable, gate-affecting triage decision to an issue.

type SizeMeasures

type SizeMeasures struct {
	Files          MeasureCountMetric   `json:"files"`
	NCLOC          MeasureCountMetric   `json:"ncloc"`
	CommentLines   MeasureCountMetric   `json:"comment_lines"`
	BlankLines     MeasureCountMetric   `json:"blank_lines"`
	Functions      MeasureCountMetric   `json:"functions"`
	CommentDensity MeasureDecimalMetric `json:"comment_density"`
}

SizeMeasures encapsulates size-related metrics such as line counts and functions.

type UnavailableReason

type UnavailableReason string
const (
	ReasonNoAnalysis                     UnavailableReason = "no_analysis"
	ReasonRatingNotAvailable             UnavailableReason = "rating_not_available"
	ReasonIssueLifecycleNotAvailable     UnavailableReason = "issue_lifecycle_not_available"
	ReasonSecurityHotspotsNotAvailable   UnavailableReason = "security_hotspots_not_available"
	ReasonChangedLineMetricsNotAvailable UnavailableReason = "changed_line_metrics_not_available"
	ReasonCoverageNotSupplied            UnavailableReason = "coverage_not_supplied"
	ReasonNoExecutableLines              UnavailableReason = "no_executable_lines"
	ReasonDuplicationNotAvailable        UnavailableReason = "duplication_not_available"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL