analyze

type Affiliation struct {
	Company    string `json:"company,omitempty"`
	ValidFrom  string `json:"validFrom,omitempty"`
	ValidUntil string `json:"validUntil,omitempty"`
	Source     string `json:"source,omitempty"`
}

type Alias struct {
	Identity   Identity `json:"identity"`
	MergedBy   string   `json:"mergedBy"`
	Confidence float64  `json:"confidence,omitempty"`
}

type Attachments struct {
	SARIF     any `json:"sarif,omitempty"`
	OpenVEX   any `json:"openvex,omitempty"`
	CycloneDX any `json:"cyclonedx,omitempty"`
	SPDX      any `json:"spdx,omitempty"`
	Scorecard any `json:"scorecard,omitempty"`
}

type BranchRecord struct {
	ID           string `json:"id"`
	Type         string `json:"type"` // "branch"
	Name         string `json:"name"`
	IsDefault    bool   `json:"isDefault,omitempty"`
	Merged       bool   `json:"merged,omitempty"`
	CreatedAt    string `json:"createdAt,omitempty"`
	LastCommitAt string `json:"lastCommitAt,omitempty"`
	AgeSeconds   *int   `json:"ageSeconds,omitempty"`
}

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

type Classification struct {
	Label      string `json:"label"`
	Thresholds string `json:"thresholds,omitempty"`
}

type Collector struct {
	Name            string  `json:"name"`
	Status          string  `json:"status"` // completed | skipped | failed | partial
	Reason          string  `json:"reason,omitempty"`
	DurationSeconds float64 `json:"durationSeconds,omitempty"`
}

type CommitRecord struct {
	ID          string     `json:"id"`
	Type        string     `json:"type"` // "commit"
	SHA         string     `json:"sha"`
	URL         string     `json:"url,omitempty"`
	Message     string     `json:"message,omitempty"`
	AuthoredAt  string     `json:"authoredAt,omitempty"`
	CommittedAt string     `json:"committedAt"`
	Author      *Identity  `json:"author,omitempty"`
	Committer   *Identity  `json:"committer,omitempty"`
	CoAuthors   []Identity `json:"coAuthors,omitempty"`
	ParentCount int        `json:"parentCount,omitempty"`
	Signature   *Signature `json:"signature,omitempty"`

	FilesChanged     int      `json:"filesChanged,omitempty"`
	Insertions       int      `json:"insertions,omitempty"`
	Deletions        int      `json:"deletions,omitempty"`
	Paths            []string `json:"paths,omitempty"`
	CycleTimeSeconds *int     `json:"cycleTimeSeconds,omitempty"`
}

type ContributorRecord struct {
	ID       string    `json:"id"`
	Type     string    `json:"type"` // "contributor"
	Identity *Identity `json:"identity"`
	Aliases  []Alias   `json:"aliases,omitempty"`

	FirstSeenAt string `json:"firstSeenAt,omitempty"`
	LastSeenAt  string `json:"lastSeenAt,omitempty"`

	Commits         int    `json:"commits,omitempty"`
	CommitsInWindow int    `json:"commitsInWindow,omitempty"`
	Insertions      int    `json:"insertions,omitempty"`
	Deletions       int    `json:"deletions,omitempty"`
	FilesTouched    int    `json:"filesTouched,omitempty"`
	TenureSeconds   *int   `json:"tenureSeconds,omitempty"`
	Status          string `json:"status,omitempty"`
}

type CrossRepoEdge struct {
	ID             string         `json:"id"`
	LocalNodeID    string         `json:"localNodeId"`
	JoinKind       string         `json:"joinKind"`
	JoinKey        string         `json:"joinKey"`
	Role           string         `json:"role"` // provides | consumes
	TargetRepoHint string         `json:"targetRepoHint,omitempty"`
	Confidence     float64        `json:"confidence,omitempty"`
	EvidenceRef    *EvidenceRef   `json:"evidenceRef,omitempty"`
	Properties     map[string]any `json:"properties,omitempty"`
}

type DependencyRecord struct {
	ID   string `json:"id"`
	Type string `json:"type"` // "dependency"
	Purl string `json:"purl"`

	BomRef        string `json:"bomRef,omitempty"`
	Ecosystem     string `json:"ecosystem,omitempty"`
	ManifestPath  string `json:"manifestPath,omitempty"`
	Scope         string `json:"scope,omitempty"`
	DiscoveredVia string `json:"discoveredVia,omitempty"`

	DeclaredVersion string `json:"declaredVersion,omitempty"`
	ResolvedVersion string `json:"resolvedVersion,omitempty"`
	LatestVersion   string `json:"latestVersion,omitempty"`
	VersionsBehind  *int   `json:"versionsBehind,omitempty"`
	PublishedAt     string `json:"publishedAt,omitempty"`
	AgeSeconds      *int   `json:"ageSeconds,omitempty"`
	EOL             bool   `json:"eol,omitempty"`
	AdvisoryCount   int    `json:"advisoryCount,omitempty"`
}

type Diagnostic struct {
	Level     string `json:"level"` // error | warning | note
	Collector string `json:"collector,omitempty"`
	MetricID  string `json:"metricId,omitempty"`
	Message   string `json:"message"`
	Caveat    bool   `json:"caveat,omitempty"`
}

type Durations struct {
	TimeToFirstResponseSeconds *int           `json:"timeToFirstResponseSeconds,omitempty"`
	TimeToFirstReviewSeconds   *int           `json:"timeToFirstReviewSeconds,omitempty"`
	TimeToCloseSeconds         *int           `json:"timeToCloseSeconds,omitempty"`
	TimeToMergeSeconds         *int           `json:"timeToMergeSeconds,omitempty"`
	TimeToAnswerSeconds        *int           `json:"timeToAnswerSeconds,omitempty"`
	TimeInLabelSeconds         map[string]int `json:"timeInLabelSeconds,omitempty"`

	// OpenEnded marks a duration measured against "now" because the item is still open. Such
	// a value grows between runs and must not be compared across reports as though it were
	// settled.
	OpenEnded bool `json:"openEnded,omitempty"`
}

type Edge struct {
	ID          string         `json:"id"`
	Kind        string         `json:"kind"`
	From        string         `json:"from"`
	To          string         `json:"to"`
	Confidence  float64        `json:"confidence,omitempty"`
	Resolution  string         `json:"resolution,omitempty"`
	EvidenceRef *EvidenceRef   `json:"evidenceRef,omitempty"`
	Properties  map[string]any `json:"properties,omitempty"`
}

type EnrichFunc func(purls []string) (map[string]PackageInsight, error)

type Evidence struct {
	Records []any `json:"records,omitempty"`
}

type EvidenceRef struct {
	Kind string `json:"kind"`

	RunIndex    *int `json:"runIndex,omitempty"`
	ResultIndex *int `json:"resultIndex,omitempty"`

	StatementIndex *int `json:"statementIndex,omitempty"`

	BomRef string `json:"bomRef,omitempty"`
	SpdxID string `json:"spdxId,omitempty"`

	Check       string `json:"check,omitempty"`
	DetailIndex *int   `json:"detailIndex,omitempty"`

	RecordID string `json:"recordId,omitempty"`
}

type FileRecord struct {
	ID   string `json:"id"`
	Type string `json:"type"` // "file"
	Path string `json:"path"`

	Language string   `json:"language,omitempty"`
	Tags     []string `json:"tags,omitempty"`

	SizeBytes  *int `json:"sizeBytes,omitempty"`
	Lines      *int `json:"lines,omitempty"`
	Code       *int `json:"code,omitempty"`
	Comments   *int `json:"comments,omitempty"`
	Blanks     *int `json:"blanks,omitempty"`
	Complexity *int `json:"complexity,omitempty"`
	Binary     bool `json:"binary,omitempty"`

	Commits       int    `json:"commits,omitempty"`
	Authors       int    `json:"authors,omitempty"`
	FirstSeenAt   string `json:"firstSeenAt,omitempty"`
	LastChangedAt string `json:"lastChangedAt,omitempty"`

	Ownership *Ownership `json:"ownership,omitempty"`
}

type Graph struct {
	Nodes          []Node           `json:"nodes,omitempty"`
	Edges          []Edge           `json:"edges,omitempty"`
	CrossRepoEdges []CrossRepoEdge  `json:"crossRepoEdges,omitempty"`
	Truncation     *GraphTruncation `json:"truncation,omitempty"`
}

type GraphElementRecord struct {
	ID        string `json:"id"`
	Type      string `json:"type"` // "graph_element"
	ElementID string `json:"elementId"`
	Element   string `json:"element,omitempty"` // node | edge | cross_repo_edge
}

type GraphTruncation struct {
	NodesOmitted int    `json:"nodesOmitted,omitempty"`
	EdgesOmitted int    `json:"edgesOmitted,omitempty"`
	FilesSkipped int    `json:"filesSkipped,omitempty"`
	Reason       string `json:"reason,omitempty"`
}

type Identity struct {
	Name        string       `json:"name,omitempty"`
	Email       string       `json:"email,omitempty"`
	Login       string       `json:"login,omitempty"`
	CanonicalID string       `json:"canonicalId,omitempty"`
	IsBot       bool         `json:"isBot,omitempty"`
	BotKind     string       `json:"botKind,omitempty"`
	BotRule     string       `json:"botRule,omitempty"`
	EmailKind   string       `json:"emailKind,omitempty"`
	Affiliation *Affiliation `json:"affiliation,omitempty"`
}

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

type IssueRecord struct {
	ID          string    `json:"id"`
	Type        string    `json:"type"` // "issue"
	URL         string    `json:"url"`
	Number      int       `json:"number,omitempty"`
	Title       string    `json:"title,omitempty"`
	Author      *Identity `json:"author,omitempty"`
	State       string    `json:"state,omitempty"`
	StateReason string    `json:"stateReason,omitempty"`
	Labels      []string  `json:"labels,omitempty"`

	CreatedAt string `json:"createdAt"`
	ClosedAt  string `json:"closedAt,omitempty"`

	// FirstResponseAt is the first comment by somebody other than the author, excluding bots.
	// Empty means no such response exists — which is not a response time of zero.
	FirstResponseAt string `json:"firstResponseAt,omitempty"`
	AnsweredAt      string `json:"answeredAt,omitempty"`

	Durations *Durations `json:"durations,omitempty"`
}

type Metric struct {
	ID         string `json:"id"`
	Family     string `json:"family"`
	Name       string `json:"name"`
	Definition string `json:"definition"`
	Unit       string `json:"unit,omitempty"`
	Statistic  string `json:"statistic,omitempty"`

	// any, because the schema allows number | string | boolean | null and an unmeasured
	// metric must stay null rather than collapsing to zero.
	Value any `json:"value"`

	Window         *MetricWindow   `json:"window,omitempty"`
	Classification *Classification `json:"classification,omitempty"`

	EvidenceSemantics    string `json:"evidenceSemantics"`
	EvidenceCompleteness string `json:"evidenceCompleteness"`
	PopulationSize       *int   `json:"populationSize,omitempty"`
	OmittedCount         int    `json:"omittedCount,omitempty"`
	TruncationReason     string `json:"truncationReason,omitempty"`

	EvidenceRefs []EvidenceRef `json:"evidenceRefs"`
	References   []Reference   `json:"references,omitempty"`
}

type MetricWindow struct {
	Since string `json:"since,omitempty"`
	Until string `json:"until,omitempty"`
	Label string `json:"label,omitempty"`
}

type Node struct {
	ID            string         `json:"id"`
	Kind          string         `json:"kind"`
	Name          string         `json:"name"`
	QualifiedName string         `json:"qualifiedName,omitempty"`
	Path          string         `json:"path,omitempty"`
	StartLine     int            `json:"startLine,omitempty"`
	EndLine       int            `json:"endLine,omitempty"`
	Language      string         `json:"language,omitempty"`
	Purl          string         `json:"purl,omitempty"`
	Exported      bool           `json:"exported,omitempty"`
	Properties    map[string]any `json:"properties,omitempty"`
}

type Options struct {
	Path string

	// WindowDays bounds the history walk. Everything derived from history is relative to it,
	// which is why the window is stamped on the report and on every metric that used it.
	WindowDays int
	MaxCommits int

	ComplexityThreshold int

	NoGit   bool
	NoFiles bool
	NoDeps  bool
	NoTrust bool
	NoForge bool

	// Silent suppresses the startup authentication line. The check still runs.
	Silent bool

	// Enrich fetches registry metadata for a batch of PURLs, so dependency staleness can be
	// computed. Nil when the user is not authenticated to the Vulnetix API — in which case the
	// staleness metrics are Unmeasured, not zero.
	Enrich EnrichFunc

	// Progress receives stage and step updates. Nil is valid and reports nothing — a long walk
	// with no output is indistinguishable from a hang, but only a terminal needs telling.
	Progress Reporter
}

type Ownership struct {
	TopAuthor       *Identity `json:"topAuthor,omitempty"`
	TopAuthorShare  float64   `json:"topAuthorShare,omitempty"`
	DistinctAuthors int       `json:"distinctAuthors,omitempty"`
}

type PackageInsight struct {
	Purl          string
	PublishedAt   *int64
	LatestVersion string
	// Versions is the ecosystem's release list, newest first.
	Versions []VersionStamp
	// Recommended is the version the ecosystem (or Safe Harbour) says to be on.
	Recommended string
	IsEOL       bool
}

type Preflight struct {
	Target Target
	Forge  *forge.Client
	Repo   forge.Repo

	// ForgeStatus explains what happened, and is printed unless silenced. Exactly one of
	// these three things is true, and the user is told which.
	ForgeStatus string
}

type PullRequestRecord struct {
	ID     string    `json:"id"`
	Type   string    `json:"type"` // "pull_request"
	URL    string    `json:"url"`
	Number int       `json:"number,omitempty"`
	Title  string    `json:"title,omitempty"`
	Author *Identity `json:"author,omitempty"`
	State  string    `json:"state,omitempty"`

	CreatedAt string `json:"createdAt"`

	// ReadyForReviewAt is the anchor every response and merge duration is measured from, so
	// that time a pull request spent in draft is not charged against its reviewers.
	ReadyForReviewAt string `json:"readyForReviewAt,omitempty"`
	FirstResponseAt  string `json:"firstResponseAt,omitempty"`
	FirstReviewAt    string `json:"firstReviewAt,omitempty"`
	ClosedAt         string `json:"closedAt,omitempty"`

	// MergedAt is set only if the pull request was actually merged. A pull request closed
	// without merging has ClosedAt and no MergedAt, and the two are never conflated.
	MergedAt string    `json:"mergedAt,omitempty"`
	MergedBy *Identity `json:"mergedBy,omitempty"`

	Additions    int `json:"additions,omitempty"`
	Deletions    int `json:"deletions,omitempty"`
	ChangedFiles int `json:"changedFiles,omitempty"`
	CommentCount int `json:"commentCount,omitempty"`

	// ReviewerCount counts distinct reviewers other than the author. A self-approval is not
	// review coverage.
	ReviewerCount int `json:"reviewerCount,omitempty"`

	// ApprovalStatus: approved | changes_requested | review_required | unknown. `unknown`
	// means no review could be resolved at all — distinct from `review_required`, which means
	// one was required and not given.
	ApprovalStatus string `json:"approvalStatus,omitempty"`

	TimeInDraftSeconds *int       `json:"timeInDraftSeconds,omitempty"`
	Durations          *Durations `json:"durations,omitempty"`
}

type Reference struct {
	Title string `json:"title,omitempty"`
	URL   string `json:"url"`
}

type Report struct {
	SchemaVersion string       `json:"schemaVersion"`
	Tool          Tool         `json:"tool"`
	Target        Target       `json:"target"`
	Run           RunMeta      `json:"run"`
	Graph         *Graph       `json:"graph,omitempty"`
	Metrics       []Metric     `json:"metrics"`
	Evidence      *Evidence    `json:"evidence,omitempty"`
	Attachments   *Attachments `json:"attachments,omitempty"`
	Diagnostics   []Diagnostic `json:"diagnostics,omitempty"`
}

type Reporter interface {
	// Stage sets what is happening now, without advancing the step count. Used for the long
	// passes, where "Walking history (3,400 commits)" is the difference between a tool that is
	// working and a tool that has hung.
	Stage(msg string)

	// Step advances to a completed step.
	Step(done int, msg string)
}

type ReviewRecord struct {
	ID             string    `json:"id"`
	Type           string    `json:"type"` // "review"
	PullRequestURL string    `json:"pullRequestUrl"`
	Reviewer       *Identity `json:"reviewer,omitempty"`
	State          string    `json:"state"`
	SubmittedAt    string    `json:"submittedAt"`
}

type RunMeta struct {
	StartedAt       string      `json:"startedAt"`
	CompletedAt     string      `json:"completedAt"`
	DurationSeconds float64     `json:"durationSeconds,omitempty"`
	HistoryWindow   *Window     `json:"historyWindow,omitempty"`
	Collectors      []Collector `json:"collectors,omitempty"`
}

type Signature struct {
	Signed       bool   `json:"signed,omitempty"`
	Verification string `json:"verification,omitempty"`
}

type Target struct {
	RepoID          string `json:"repoId"`
	OrgKey          string `json:"orgKey,omitempty"`
	RemoteURL       string `json:"remoteUrl,omitempty"`
	DefaultBranch   string `json:"defaultBranch,omitempty"`
	HeadCommit      string `json:"headCommit,omitempty"`
	HeadCommittedAt string `json:"headCommittedAt,omitempty"`
	RootPath        string `json:"rootPath,omitempty"`
}

type Tool struct {
	Name           string `json:"name"`
	Version        string `json:"version"`
	Commit         string `json:"commit,omitempty"`
	CatalogVersion string `json:"catalogVersion,omitempty"`
}

type VersionStamp struct {
	Version     string
	PublishedAt *int64
}

type Window struct {
	Since         string `json:"since,omitempty"`
	Until         string `json:"until,omitempty"`
	CommitsWalked int    `json:"commitsWalked,omitempty"`
	CommitLimit   int    `json:"commitLimit,omitempty"`
}