detect

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

type BuildFunc func(ctx context.Context, partial *Proposal) (BuildOutcome, error)

type BuildOutcome struct {
	Built    *Built
	PullAuth *api.RegistryAuth

	// Plan is the build plan the image was built from, when the builder
	// steered the proposed one after a build of it failed: what the proposal
	// carries from then on, so the spec says how its image was made (R-020).
	// Nil when the proposed plan was built as it was.
	Plan map[string]string
}

type BuildPlanner interface {
	// The plan's Declared is what in the repository dictated it, or nil when
	// convention-matching chose it. The builder knows which it was; detection
	// shows it, and cannot derive it without a second copy of the same reading.
	Plan(ctx context.Context, src api.SourceView) (api.BuildPlan, error)

	// PlanPrebuild is the repository's Dockerfile with the repository's own
	// build run before it, when the Dockerfile copies what that build makes
	// and the repository does not have it — target/*.war before `mvn
	// package`. An empty plan when the Dockerfile builds as it is.
	PlanPrebuild(ctx context.Context, src api.SourceView, dockerfile string) (api.BuildPlan, error)
}

type Builder interface {
	Build(ctx context.Context, req api.BuildRequest) (api.BuildResult, error)
}

type BuildpackDetector struct {
	// Planner turns a repository with no deployment instructions into build
	// inputs. Supplied by the builder adapter, because what those inputs are is
	// the builder's vocabulary and core does not learn it (R-251): core asks
	// "how would you build this", stores whatever comes back, and interprets
	// none of it.
	//
	// Nil means detection still recognizes the language and asks its questions;
	// the plan simply is not part of the proposal, and the builder makes one at
	// build time instead. That is the behavior every install had before the
	// plan was reviewable.
	Planner BuildPlanner
}

type Built struct {
	// Inputs is spec.BuildInputs of the spec it was built from.
	Inputs string `json:"inputs"`

	// Source is the checkout it was built from: a commit, or an upload's
	// digest (source.Checkout.Identity).
	Source string `json:"source"`

	// Image is the app's image, by ID or by digest. Empty for a compose app,
	// whose services each have their own.
	Image string `json:"image,omitempty"`

	// Images are a compose app's built services' images, by workload name.
	Images map[string]string `json:"images,omitempty"`
}

type Candidate struct {
	Detector string             `json:"detector"`
	Strategy spec.BuildStrategy `json:"strategy"`

	// Confidence is 0..1. It is shown to the user, so it has to mean something
	// consistent across detectors: how sure this detector is that its strategy
	// is the right one, not how much it would like to win.
	Confidence float64 `json:"confidence"`

	// Evidence is human-readable and shown in the review UI, so a person can
	// see why Pando thinks what it thinks (R-102).
	Evidence []string `json:"evidence,omitempty"`

	// Questions are what this detector could not determine. Held to R-105.
	Questions []Question `json:"questions,omitempty"`

	// Draft is what this detector would put in the spec.
	//
	// Serialized, and it has to be. The auction asks which of two close
	// readings is right (see tieBreak), and answering that means adopting the
	// other candidate's draft — impossible if the losing drafts were discarded
	// when the proposal was stored. They were, so the answer could do nothing
	// but stamp the chosen strategy's *name* onto the winner's draft: choosing
	// "compose" produced the Dockerfile detector's spec labeled
	// `strategy: compose`, which no builder implements, and the app was refused
	// at plan time with a message about the builder.
	Draft Draft `json:"draft,omitempty"`

	// Spec is this candidate's draft, assembled and completed with the
	// install's defaults — the thing accepting it would actually pin.
	//
	// Every candidate carries one, not just the winner, because any of them can
	// be adopted by answering the tie-break. Completing only the winner meant an
	// adopted runner-up arrived with no builder, no routing and no port, and
	// the deploy failed on "0 is not a usable port number" with nothing
	// pointing at why.
	Spec *spec.AppSpec `json:"spec,omitempty"`

	// Blocked is set when a detector recognizes the repository and cannot
	// proceed with it — a compose file using a construct that cannot cross the
	// boundary (R-099) is the case this exists for.
	//
	// It is deliberately not an error returned from Bid. The auction drops a
	// detector that errors, because one broken detector must not fail
	// detection; a blocked candidate dropped the same way would leave the user
	// with a buildpack guess and no idea why their compose file was ignored.
	// The reason is the most useful thing Pando has here, so the candidate
	// stays in the auction and carries it.
	Blocked error `json:"-"`
}

type ComposeDetector struct{}

type Detector interface {
	// Name identifies the detector in the auction result.
	Name() string

	// Bid returns this detector's reading of the source. A detector that sees
	// nothing it recognizes returns zero confidence rather than a guess.
	Bid(ctx context.Context, src api.SourceView) (Candidate, error)
}

type DockerfileDetector struct {
	// Planner, when there is one, runs the repository's own build ahead of a
	// Dockerfile that copies its output (BuildPlanner.PlanPrebuild). Nil
	// builds the Dockerfile as it is.
	Planner BuildPlanner
}

type Draft struct {
	Workloads []spec.Workload `json:"workloads,omitempty"`
	Volumes   []spec.Volume   `json:"volumes,omitempty"`
	Slots     []spec.Slot     `json:"slots,omitempty"`
	Build     spec.Build      `json:"build"`
	Health    spec.Health     `json:"health,omitempty"`
	Warnings  []spec.Warning  `json:"warnings,omitempty"`
}

type ImageReader interface {
	Inspect(ctx context.Context, appID, reference string, want oci.Platform) (oci.Inspection, error)
	Auth(ctx context.Context, appID, reference string) (*oci.Auth, error)
}

type Job struct {
	Auction  *Auction
	Registry RegistryProbe
	Runtime  TrialRunner
	Builder  Builder

	// Images reads an image app's image from its registry before the trial,
	// with the app's credential: its digest, platforms and configuration.
	Images ImageReader

	// TrialTimeout bounds the observation. Zero uses DefaultTrialTimeout.
	TrialTimeout time.Duration

	// NewTrialID names the throwaway bundle. Injectable so a test can assert
	// what was created and cleaned up.
	NewTrialID func() string
}

type MonorepoDetector struct{}

type ProgressFunc func(stage string, partial *Proposal)

type Proposal struct {
	Status    string       `json:"status"`
	Winner    Candidate    `json:"winning_bid"`
	RunnersUp []Candidate  `json:"runners_up"`
	Questions []Question   `json:"questions"`
	DraftSpec spec.AppSpec `json:"draft_spec"`

	// Blocked is the reason, when the best reading of this repository is one
	// that cannot proceed — a compose file using a construct that cannot cross
	// the boundary (R-099).
	Blocked *errs.Error `json:"blocked,omitempty"`

	// TrialLog is the app's own output from the trial run. On a crash this is
	// the entire answer Pando has, and R-107 says showing it and stopping is
	// the correct outcome rather than a gap to close with inference.
	TrialLog string `json:"trial_log,omitempty"`

	// Commit is what was actually read. R-120: Ref is what the user asked for,
	// Commit is what runs.
	Commit string `json:"commit,omitempty"`

	// Trial is what the trial run observed, minus the log, which TrialLog
	// already carries.
	//
	// Kept on the proposal because the log is not the whole of what the trial
	// established and two things need the rest of it. A screening pass has to
	// know whether the app crashed, because that is what decides whether a
	// dependency it found may be marked required (O-4's fallback, design 10
	// §3.2). And "no trial ran" and "a trial ran and saw nothing" are different
	// facts that an empty log reports identically.
	Trial TrialObservation `json:"trial,omitzero"`

	// LoopbackCommand is the command the trial started the app with when it
	// listened only on 127.0.0.1, where it can be told: the answer to the
	// question that asks for a command that moves it cannot be this one
	// (CheckAnswers).
	LoopbackCommand string `json:"loopback_command,omitempty"`

	// Built is the image detection built for this proposal, when it built one
	// (R-311): what the plan's score was read from, and what a deploy of the
	// same build inputs runs instead of building again. Nil for an app that
	// runs a published image, and for one whose build waits on an answer.
	Built *Built `json:"built,omitempty"`

	// Screening is what an AI adapter made of this proposal (R-331, design 10
	// §5): which adapter, which model, what it read, what it changed and why,
	// and what it asked for that Pando refused.
	//
	// On the proposal rather than only in the audit log, because the console
	// renders it as a section of the review. R-334 calls for attribution, and
	// attribution nobody can see is a record rather than attribution.
	//
	// Nil means no screening ran, which is the ordinary case for an install
	// with no AI adapter configured — and not a degraded one (R-335).
	Screening *screening.Outcome `json:"screening,omitempty"`

	// Conversation is what a person reviewing this proposal asked an AI adapter
	// to change, and what it replied and did (R-336's third trigger), oldest
	// first. On the proposal because it is about this reading of this commit:
	// detecting again starts a new one.
	Conversation []Turn `json:"conversation,omitempty"`
}

type PublishedImage struct {
	Ref      string `json:"ref"`
	Digest   string `json:"digest,omitempty"`
	Registry string `json:"registry"`
}

type Question struct {
	Key     string           `json:"key"`
	Prompt  string           `json:"prompt"`
	Why     string           `json:"why"`
	Kind    api.QuestionKind `json:"kind"`
	Options []string         `json:"options,omitempty"`

	// Deferred marks a question the trial run is expected to answer (R-097).
	//
	// This is the difference between something Pando does not know and something
	// a person has to tell it. A port is the clearest case: R-097 exists so that
	// Pando watches the app bind rather than asking, and R-005 says the person
	// deploying may not know what a port is. Holding such a question against the
	// questions-per-deploy budget would count a cost nobody pays.
	//
	// The question is still carried, because the trial run can fail to observe
	// an answer — at which point it stops being deferred and is put to a person.
	Deferred bool `json:"deferred,omitempty"`

	// Suggested is an AI adapter's answer to this question (R-338).
	//
	// Carried on the question rather than folded into the draft spec, so the
	// question stays on the page and a person can see the answer, check its
	// reason, and change it with the same request that answers any question.
	// It counts as an answer until a person gives one; a person's answer wins.
	Suggested *Suggestion `json:"suggested,omitempty"`
}

type RegistryProbe interface {
	// Published reports images published for a source repository, best first.
	// No result is the normal case and not an error.
	Published(ctx context.Context, src spec.Source) ([]PublishedImage, error)
}

type Result struct {
	Winner    Candidate   `json:"winning_bid"`
	RunnersUp []Candidate `json:"runners_up"`

	// Questions are the winner's, plus anything the auction itself could not
	// settle — such as which of two close bids is right.
	Questions []Question `json:"questions"`

	Status string `json:"status"`

	// Blocked is the winner's reason, when the best reading of this repository
	// is one that cannot proceed. Surfacing it is the whole point: "your
	// compose file sets privileged: true, and here is why that cannot run" is
	// an answer, and silently falling through to a language guess is not.
	Blocked error `json:"-"`
}

type StaticDetector struct{}

type Suggestion struct {
	Value    string   `json:"value"`
	Reason   string   `json:"reason,omitempty"`
	Evidence []string `json:"evidence,omitempty"`
}

type Trial struct {
	// Ran is false when no trial happened — no runtime configured, or one that
	// does not support it. Distinguished from a trial that ran and observed
	// nothing, because the first leaves questions unanswered and the second is
	// information.
	Ran bool

	Started bool
	Crashed bool

	// Exited is a process that finished on its own with status 0 while it was
	// watched: a command-line program or a script, not a server (R-107).
	Exited bool

	ObservedPorts []int
	LoopbackPorts []int

	// HTTPProbed is true when the runtime sent each observed port an HTTP
	// request, and HTTPAnswers are the ports that answered (observedPorts).
	HTTPProbed  bool
	HTTPAnswers []api.HTTPAnswer

	// HTTPProbedPorts are the observed ports the runtime actually asked
	// (api.TrialResult.HTTPProbedPorts); noHTTPRefusal reads them.
	HTTPProbedPorts []int

	ObservedWrites []string
	ImageVolumes   []string
	Log            string
}

type TrialObservation struct {
	Ran            bool     `json:"ran,omitempty"`
	Started        bool     `json:"started,omitempty"`
	Crashed        bool     `json:"crashed,omitempty"`
	ObservedPorts  []int    `json:"observed_ports,omitempty"`
	ObservedWrites []string `json:"observed_writes,omitempty"`
}

type TrialRunner interface {
	Capabilities(ctx context.Context) (api.RuntimeCapabilities, error)
	Trial(ctx context.Context, req api.TrialRequest) (api.TrialResult, error)
}

type Turn struct {
	// From is TurnPerson or TurnAI.
	From string    `json:"from"`
	Text string    `json:"text"`
	At   time.Time `json:"at"`

	// Changes and Refused are what an AI turn did to the plan, one line each:
	// the applied amendments' summaries, and what Pando would not do with its
	// reason (R-334).
	Changes []string `json:"changes,omitempty"`
	Refused []string `json:"refused,omitempty"`

	// FilesRead is what an AI turn read (R-337), so the next one can start
	// from it rather than read it all again (api.ScreenRequest.Known).
	FilesRead []string `json:"files_read,omitempty"`
}