fix: add cue definitions for embedded types

[trumant]

This change refactors some embedded types within existing definitions into definitions themselves.

This provides a pathway to much better go types being generated by make cuegen and solving some of the pain observed in https://github.com/revanite-io/pvtr-github-repo/blob/main/evaluation_plans/reusable_steps/evaluations_test.go#L21

This results in the following generated go types:

// Code generated by "cue exp gengotypes"; DO NOT EDIT.

package si

// URL is a TLS URL
type URL string

// Email is a valid email address
type Email string

// Date is a date in the format YYYY-MM-DD
type Date string

// SchemaVersion is a version string in the format X.Y.Z
type SchemaVersion string

// Assessment represents the results of a security assessment, including comments, evidence, and date.
type Assessment struct {
	// Notes or commentary about the findings or purpose of the assessment.
	Comment string `json:"comment"`

	// The name or identifier of the assessment artifact.
	Name *string `json:"name,omitempty"`

	// The URL where the assessment report or artifact is located.
	Evidence *URL `json:"evidence,omitempty"`

	// The date the assessment was published.
	Date Date `json:"date,omitempty"`
}

// Attestation describes an [in-toto attestation](https://github.com/in-toto/attestation/blob/main/spec/README.md#in-toto-attestation-framework-spec), including its name, location, predicate URI, and any additional comments.
type Attestation struct {
	// The name or identifier of the attestation.
	Name string `json:"name"`

	// A web location where the attestation can be found.
	Location URL `json:"location"`

	// A URI to a resource describing the attestation’s predicate or specification.
	PredicateURI string `json:"predicate-uri"`

	// Additional context or instructions for using the attestation.
	Comment *string `json:"comment,omitempty"`
}

// Contact represents a person or entity responsible for the project, including their name, affiliation, and contact details.
type Contact struct {
	// The contact person's name.
	Name string `json:"name"`

	// Indicates whether this admin is the first point of contact for inquiries. Only one entry should be marked as primary.
	Primary bool `json:"primary"`

	// The entity with which the contact is affiliated, such as a school or employer.
	Affiliation *string `json:"affiliation,omitempty"`

	// A preferred email address to reach the contact.
	Email *Email `json:"email,omitempty"`

	// A social media handle or profile for the contact.
	Social *string `json:"social,omitempty"`
}

type License struct {
	// A web address where the license can be found.
	Url URL `json:"url"`

	// The SPDX license expression for the license.
	Expression string `json:"expression"`
}

type Link struct {
	// A link to a resource, not restricted to http/s.
	Uri string `json:"uri"`

	// Instructions or information about the link.
	Comment string `json:"comment"`
}

// The ProjectRepository object describes a repository that is part of a project, including its name, comment, and URL.
type ProjectRepository struct {
	// The name or short label of the repository.
	Name string `json:"name"`

	// Explanation of the repository purpose or contents and its relation to the rest of the project.
	Comment string `json:"comment"`

	// The URL where the repository is hosted.
	Url URL `json:"url"`
}

// SecurityInsights defines the schema defining how projects can to report information about their security in a machine-processable way. The data tracked within this specification is intended to fill the gaps between simplified solutions such as SECURITY.md and comprehensive automated solutions such as SBOMs. In that gap lay elements that must be self-reported by projects to allow end-users to make informed security decisions.
type SecurityInsights struct {
	// header captures high level metadata about the schema.
	Header Header `json:"header"`

	// project describes the overall project, including basic info, documentation links, repositories, vulnerability reporting, and security details. This field is not required if `header.project-si-source` is supplied.
	Project *Project `json:"project,omitempty"`

	// repository describes repository-related configurations, including status, policies, team members, documentation, license, releases, and security posture. This field is not required if `header.project-si-source` is supplied. This field is required if the file is intended for use as a parent security insights file with project information to be inherited by multiple repositories via their respective `header.project-si-source`.
	Repository *Repository `json:"repository,omitempty"`
}

// The Header object captures high-level metadata about the schema.
type Header struct {
	// The date when the document or data was last reviewed.
	LastReviewed Date `json:"last-reviewed"`

	// The date when the document or data was last updated.
	LastUpdated Date `json:"last-updated"`

	// The version of the Security Insights schema being used.
	SchemaVersion SchemaVersion `json:"schema-version"`

	// The primary reference URL for this schema’s origin or repository.
	URL URL `json:"url"`

	// Additional information about the schema.
	Comment *string `json:"comment,omitempty"`

	// A URL to the security insights file that contains project information for this file to inherit. The URL provided here should respond to an unauthenticated GET request and return a valid security insights file using a content-type of "text/plain" or "application/yaml". This is useful for projects that are part of a larger organization or ecosystem, where much of the security insights data is shared across multiple projects.
	ProjectSISource *URL `json:"project-si-source,omitempty"`
}

// ProjectDocumentation contains links to various documents related to the project, including detailed guides, code of conduct, quickstart guides, release processes, support policies, and signature verification.
type ProjectDocumentation struct {
	// URL to more extensive or advanced documentation.
	DetailedGuide *URL `json:"detailed-guide,omitempty"`

	// URL to the document outlining contributor and user conduct guidelines.
	CodeOfConduct *URL `json:"code-of-conduct,omitempty"`

	// URL to a concise guide to basic functionality for new users.
	QuickstartGuide *URL `json:"quickstart-guide,omitempty"`

	// URL describing how releases are planned, prepared, and published.
	ReleaseProcess *URL `json:"release-process,omitempty"`

	// URL to documentation describing how releases are supported. See [Recommendations for publishing End-of-life dates and support timelines](https://endoflife.date/recommendations) for best practices.
	SupportPolicy *URL `json:"support-policy,omitempty"`

	// URL to documentation explaining how to verify digital signatures on assets.
	SignatureVerification *URL `json:"signature-verification,omitempty"`
}

// VulnerabilityReporting describes how security vulnerabilities can be reported and how they are handled by the project.
type VulnerabilityReporting struct {
	// Indicates whether this project currently accepts vulnerability reports.
	ReportsAccepted bool `json:"reports-accepted"`

	// Specifies whether a bug bounty program is offered.
	BugBountyAvailable bool `json:"bug-bounty-available"`

	// Path to a page providing details about any bug bounty program.
	BugBountyProgram *URL `json:"bug-bounty-program,omitempty"`

	// Point of contact for reporting vulnerabilities. This may be a single person or a mailgroup.
	Contact *Contact `json:"contact,omitempty"`

	// Additional comments or instructions about vulnerability reporting.
	Comment *string `json:"comment,omitempty"`

	// Path to a page containing guidelines for security-related disclosures.
	SecurityPolicy *URL `json:"security-policy,omitempty"`

	// The PGP public key for secure communication.
	PGPKey *URL `json:"pgp-key,omitempty"`

	// A list of issues or components that are covered by the vulnerability reporting process.
	InScope *URL `json:"in-scope,omitempty"`

	// A list of issues or components not covered by the vulnerability reporting process.
	OutOfScope *URL `json:"out-of-scope,omitempty"`
}

// Project describes the overall project, including basic info, documentation links, repositories, vulnerability reporting, and security details.
type Project struct {
	// The name of the project.
	Name string `json:"name"`

	// A path to the project’s landing page. This may be a project website, a version control system repository, or a project/organization page in the VCS.
	HomePage *URL `json:"homepage,omitempty"`

	// A URL pointing to a roadmap or schedule for planned features and releases.
	Roadmap *URL `json:"roadmap,omitempty"`

	// A URL to information about sponsorships, donations, or other funding topics.
	Funding *URL `json:"funding,omitempty"`

	// This field is to communicate the relationship between the project and "a legal person, other than a manufacturer, that has the purpose or objective of systematically providing support on a sustained basis for the development of specific products with digital elements, qualifying as free and open-source software and intended for commercial activities, and that ensures the viability of those products" This definition is drawn from the [European Union Cyber Resilience Act, Article 3](https://eur-lex.europa.eu/eli/reg/2024/2847/oj/eng#art_3).
	Steward *Link `json:"steward,omitempty"`

	// A list of 1 or more individuals who have administrative access to the project's resources.
	Administrators []Contact `json:"administrators"`

	// A list of 1 or more repositories that are part of this project, including the repository this file is published in.
	Repository []ProjectRepository `json:"repositories"`

	// An object describing how security vulnerabilities can be reported and how they are handled by the project.
	VulnerabilityReporting VulnerabilityReporting `json:"vulnerability-reporting"`

	// the project's documentation resources
	Documentation *ProjectDocumentation `json:"documentation,omitempty"`
}

// SecurityToolIntegration describes how a security tool is integrated into the repository, including whether it is used in scheduled processes, continuous integration, or during the release process.
type SecurityToolIntegration struct {
	// Indicates whether the tool is used in a scheduled process or supports an on-demand.
	Adhoc bool `json:"adhoc"`

	// Indicates whether the tool is used in the continuous integration process.
	Ci bool `json:"ci"`

	// Indicates whether the tool is run before or during the release process.
	Release bool `json:"release"`
}

// SecurityToolResults describes the results of security scans, including those run on-demand, in continuous integration, and during the release process.
type SecurityToolResults struct {
	// Results of scheduled or on-demand security scans.
	Adhoc *Attestation `json:"adhoc,omitempty"`

	// Results of security scans run in the continuous integration process.
	CI *Attestation `json:"ci,omitempty"`

	// Results of security scans run in the build and release process.
	Release *Attestation `json:"release,omitempty"`
}

// SecurityTool describes a security-related tool used in the repository, including its name, type, version, rulesets, integration details, and results.
type SecurityTool struct {
	// The name of the tool.
	Name string `json:"name"`

	// The general category or type of the tool.
	Type string `json:"type"`

	// The version of the tool that is used.
	Version *string `json:"version,omitempty"`

	// Additional notes about the tool’s usage or configuration.
	Comment *string `json:"comment,omitempty"`

	// The set of rules or configurations applied by the tool. If customization is not enabled, the only value here should be "default".
	Rulesets []string `json:"rulesets"`

	// An object describing how the tool is integrated with the project.
	Integration SecurityToolIntegration `json:"integration"`

	Results SecurityToolResults `json:"results"`
}

// SecurityPosture describes the security posture of the repository, including assessments, champions, and tools.
type SecurityPosture struct {
	// An object describing security assessments for the repository.
	Assessments struct {
		// Results of the contributor team's assessment of software produced by this repository.
		Self Assessment `json:"self"`

		// Results of third-party assessments of software produced by this repository.
		ThirdPartyAssessment []Assessment `json:"third-party,omitempty"`
	} `json:"assessments"`

	// A list of core team members who advocate for continuous improvement of security practices. These individuals may take responsibility for security reviews, training, interfacing with stakeholders on security topics, or other similar activities.
	Champions []Contact `json:"champions,omitempty"`

	// A list of objects describing security-related tools used in the repository.
	Tools []SecurityTool `json:"tools,omitempty"`
}

// RepositoryDocumentation contains links to various documents related to the repository, including contributing guides, dependency management policies, governance documents, and review policies.
type RepositoryDocumentation struct {
	// URL to a document outlining the process for contributing to the repository.
	ContributingGuide *URL `json:"contributing-guide,omitempty"`

	// URL to a document outlining the process for managing dependencies in the repository.
	DependencyManagementPolicy *URL `json:"dependency-management-policy,omitempty"`

	// URL to any governance documents regarding roles, responsibilities, processes, and decision-making.
	Governance *URL `json:"governance,omitempty"`

	// URL to a document outlining the process for reviewing changes to the repository.
	ReviewPolicy *URL `json:"review-policy,omitempty"`

	// URL with information about the repository's security, including the policy for reporting security vulnerabilities.
	SecurityPolicy *URL `json:"security-policy,omitempty"`
}

// ReleaseDetails describes the release process for the repository, including automated pipelines, distribution points, changelogs, licenses, and attestations.
type ReleaseDetails struct {
	// Indicates if the repository uses an automated release pipeline.
	AutomatedPipeline bool `json:"automated-pipeline"`

	// A list of 1 or more links describing where the repository’s releases are distributed. This may be the VCS releases page, a package manager, or other distribution points.
	DistributionPoints []Link `json:"distribution-points"`

	// A URL to the repository’s release changelog. The URL value should include placeholders such as `{version}` if relevant.
	Changelog *URL `json:"changelog,omitempty"`

	// Describes the license details specifically for releases. This should be used when the release license differs from the repository license.
	License *License `json:"license,omitempty"`

	// List of attestations for the repository’s releases.
	Attestations []Attestation `json:"attestations,omitempty"`
}

// The Repository object specifies repository-related configurations, including status, policies, team members, documentation, license, releases, and security posture.
type Repository struct {
	// Indicates the repository’s current [Repo Status](https://repostatus.org).
	Status string `json:"status"`

	// The main URL for this repository.
	Url URL `json:"url"`

	// Indicates whether the repository currently accepts any change requests.
	AcceptsChangeRequest bool `json:"accepts-change-request"`

	// Indicates whether the repository accepts automated or machine-generated change requests.
	AcceptsAutomatedChangeRequest bool `json:"accepts-automated-change-request"`

	// Specifies whether the repository only accepts bug-fixes and not feature work.
	BugFixesOnly bool `json:"bug-fixes-only,omitempty"`

	// Indicates whether the repository universally avoids package dependencies from outside of the project.
	NoThirdPartyPackages bool `json:"no-third-party-packages,omitempty"`

	// A list of 1 or more core team members for this repository, such as maintainers or approvers.
	CoreTeam []Contact `json:"core-team"`

	// The license information for this repository.
	License License `json:"license"`

	// An object describing security-related artifacts, champions, and tooling for the repository.
	SecurityPosture SecurityPosture `json:"security"`

	// Documentation links for the repository, including links to contributing guides, dependency management policies, governance documents, and review policies.
	Documentation *RepositoryDocumentation `json:"documentation,omitempty"`

	// Release describes the release process for the repository.
	ReleaseDetails *ReleaseDetails `json:"release,omitempty"`
}

[trumant]

In integrating this work into ossf/si-tooling and then into revanite-io/pvtr-github-repo I'm a bit on the fence about the naming of fields like:

1. Repository.RepositoryDocumentation
2. SecurityTool.SecurityToolIntegration
3. SecurityTool.SecurityToolResults

Curious to hear opinions from reviewers as to whether they should stay as-is or remove the "stutter" and adopt:

1. Repository.Documentation
2. SecurityTool.Integration
3. SecurityTool.Results

[trumant]

In integrating this work into ossf/si-tooling and then into revanite-io/pvtr-github-repo I'm a bit on the fence about the naming of fields like:

1. Repository.RepositoryDocumentation
2. SecurityTool.SecurityToolIntegration
3. SecurityTool.SecurityToolResults

Curious to hear opinions from reviewers as to whether they should stay as-is or remove the "stutter" and adopt:

1. Repository.Documentation
2. SecurityTool.Integration
3. SecurityTool.Results

This renaming has been done.