pipeline

type Level int

type LicensePolicy struct {
	// Mode is "inclusive" or "individual".
	Mode string
	// AllowCSV is a comma-separated SPDX allowlist.
	AllowCSV string
	// AllowFile is a path to a newline-separated SPDX allowlist.
	AllowFile string
	// PolicyFile and ExceptionsFile are the declarative forms of the same
	// decision: a category-based policy and its approved exceptions. Empty
	// means "discover the default path under the scanned root, and fall back to
	// the built-in policy" — so a project that has neither behaves exactly as
	// it did before they existed.
	PolicyFile     string
	ExceptionsFile string
}

type Options struct {

	// Files are the manifests and SBOMs already detected under RootPath. The
	// caller runs detection so it can report and filter before committing to a
	// scan.
	Files []scan.DetectedFile

	// RootPath is the absolute directory being analysed.
	RootPath string

	// Depth bounds directory recursion during manifest detection (--depth).
	Depth int

	// Excludes are glob patterns removed from the walk (--exclude).
	Excludes []string

	// Deployment labels where these results are deployed and who owns them
	// (--project/--cluster/--namespace/--environment/--tag). It is inert for
	// the analysis itself — nothing branches on it — and exists so the labels
	// reach the CycloneDX metadata and the upload envelope, where the server
	// can join results across repositories. See internal/cdx/deployment.go.
	Deployment cdx.DeploymentContext

	// ManufacturerSources are the candidates for the organization that created
	// metadata.manufacturer, which is the field for documents produced by an
	// automated process. It is the organization running this scan, not the
	// vendor of the scanner; the scanner is named in metadata.tools. Nil when
	// nothing resolved it, which leaves the member absent rather than guessed.
	// Resolved by the caller because only it has the command's flags.
	ManufacturerSources cdx.ManufacturerSources

	// LifecycleOverride replaces the capture stages the engine would derive from
	// what it read (--lifecycle). Nil means derive. A pipeline that states its
	// own stage is making a claim about its process that no amount of filesystem
	// inspection can contradict, so the override wins outright.
	LifecycleOverride []cdx.LifecyclePhase

	// VEXFiles are third-party VEX documents to apply to the findings before
	// the quality gates are evaluated (--vex-file). Empty when --no-vex was
	// passed, so the engine has one thing to check rather than two.
	VEXFiles []string

	NoSCA        bool
	NoSASTRules  bool
	NoSecrets    bool
	NoContainers bool
	NoIAC        bool
	NoLicenses   bool

	// NoExploits and NoRemediation drop the corresponding VDB enrichment
	// passes; the SCA lookup itself still runs.
	NoExploits    bool
	NoRemediation bool

	// SeverityThreshold is validated against scan.ValidSeverityThresholds.
	SeverityThreshold string
	// ExploitThreshold is validated against scan.ValidExploitThresholds.
	ExploitThreshold string
	BlockMalware     bool
	BlockEOL         bool
	BlockUnpinned    bool
	VersionLag       int
	CooldownDays     int

	// Jail runs the organisation's jail policy against this repository after the
	// scan has uploaded, and gates on the verdict.
	//
	// Unlike the thresholds above, which grade THIS run's findings, the jail
	// policy grades the repository's accumulated state across every tool and
	// category that has reported for it. A breach exits 1 alongside the other
	// gates; a rule that cannot be evaluated against current scan coverage exits
	// 3, which is a different problem with a different owner.
	Jail bool

	// DisableDefaultRules drops the embedded corpus, leaving only RuleRefs.
	DisableDefaultRules bool
	// RuleRefs are external rule packs, cloned from RuleRegistry.
	RuleRefs []sast.RuleRef
	// RuleRegistry defaults to sast.DefaultRegistry when empty.
	RuleRegistry string
	// RuleID restricts the run to a single VNX-NNNN rule.
	RuleID string
	// LockedKinds restricts the run to these rule kinds, embedded and external
	// alike. Nil means "no lock", which is the generic scan command's
	// behaviour. The language server sets this per trigger: the keystroke path
	// runs sast/iac/oci only, because the 1,092 secrets rules cost roughly 20x
	// what every other kind costs combined.
	LockedKinds []string
	// SnippetContext shapes SARIF snippets: -1 picks a width from the finding
	// span, 0 disables snippets.
	SnippetContext int

	// Reachability selects the tree-sitter reachability mode applied to the
	// CVEs the SCA pass produces: "direct" scans only each vulnerable
	// package's installed directory, "transitive" sweeps the rest of the
	// project for callers, "both" does both, and "off" skips the analysis (and
	// the server-side query fetch) entirely. Empty means "both".
	//
	// It is a string rather than a reachability.Mode so internal/pipeline stays
	// free of the CGo tree-sitter dependency; the value is validated by
	// internal/scanopts before it gets here.
	Reachability string

	IgnoreGlobs          []string
	IgnoreGit            bool
	IgnoreBinaries       bool
	GitHistory           bool
	GitHistoryMaxCommits int
	GitHistoryMaxFiles   int
	// RespectGitignore prunes files matched by .gitignore.
	RespectGitignore bool

	SCAAutofix     bool
	SCAAutofixOpts fix.Options
	// AutofixResolved carries findings a previous autofix pass fixed, so the
	// confirmation re-scan can mark them resolved rather than re-reporting.
	AutofixResolved []*triage.TriageFinding

	License LicensePolicy

	GitCtx  *gitctx.GitContext
	SysInfo *gitctx.SystemInfo
	// SeedBOM and VulnetixSeedBOM carry components from an existing SBOM into
	// the produced document, so a scan never loses what a previous one found.
	SeedBOM         *cdx.BOM
	VulnetixSeedBOM *cdx.BOM

	// ShowPaths includes the dependency chain that introduced each package.
	ShowPaths bool
	// ResultsOnly suppresses all output when the run is clean.
	ResultsOnly bool
	// DryRun performs detection, parsing and memory reads with zero API calls.
	DryRun bool
	// NoProgress suppresses the live progress row. Kept here because it also
	// reaches callees that build their own display contexts.
	NoProgress bool
}

type Reporter interface {
	// Stage changes the current stage label without changing numeric progress.
	Stage(stage string)

	// Update sets numeric progress out of the total declared at construction,
	// and, when stage is non-empty, the stage label with it.
	Update(done int, stage string)

	// Logf writes one diagnostic line. Callers must not append a newline.
	Logf(level Level, format string, args ...any)

	// Degraded records that part of the analysis did not run to completion:
	// files skipped over the size cap, git history unavailable, a stage that
	// failed without failing the run. These are collected and surfaced, because
	// "no findings" and "did not look" must not be indistinguishable.
	Degraded(note string)

	// Degradations returns everything passed to Degraded, in order.
	Degradations() []string

	// Complete and Fail finalise the run exactly once. Subsequent calls are
	// ignored, so a deferred Complete after an early Fail is harmless.
	Complete(stage string)
	Fail(stage string)

	// Writer is the transitional escape hatch for callees that still take an
	// io.Writer directly (sast.LoadAllModules, autofix.RunInstall,
	// postScanSARIF). Everything written to it is ordinary log output. New code
	// should use Logf; this exists so the extraction could land without also
	// rewriting every callee's signature in the same change.
	Writer() io.Writer
}

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

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