detect

type Candidate struct {
	// Path is the file's path within the scanned filesystem, slash-separated.
	Path string
	// Weight scores how likely the file is to hold the component's own license.
	// Files in the root carry RootWeightBonus on top of their filename weight.
	Weight float64
	// Excluded says why the file is not evidence about this component, and is
	// empty for a file that is. ScopeProject never returns a file excluded as
	// vendored or build-output, since it does not descend into those trees.
	Excluded ExclusionReason
}

type Classifier interface {
	// Identify classifies the contents of one file, returning one Match per
	// distinct license recognized in it, in the classifier's own order.
	Identify(fsys fs.FS, path string) ([]Match, error)
	// IdentifyHeader matches a license notice in source text.
	IdentifyHeader(data []byte) []HeaderMatch
}

type Conclusion struct {
	// Expression is the SPDX expression the evidence settles on, and is empty
	// exactly when Reason is not ReasonSettled.
	Expression string
	// Reason says why no expression was reached.
	Reason Reason
	// Identifiers are the distinct SPDX identifiers found in scope, sorted.
	// It is populated whether or not an expression was reached, so a caller
	// reporting an ambiguity can say what the licenses were.
	Identifiers []string
	// GrantBasis says where a GPL-family version grant came from, and is empty
	// when no license involved has one.
	GrantBasis GrantBasis
	// Unrecognized are the in-scope files holding license text that nothing
	// identified, in discovery order. A caller minting a LicenseRef names it
	// from the text of the first of these, which UnrecognizedText returns.
	Unrecognized []File
	// Files are the in-scope files the conclusion was drawn from.
	Files []File
}

type Declaration struct {
	// License is the declared SPDX expression, exactly as declared. It is not
	// canonicalized here: reporting what was written is what lets a
	// disagreement be attributed to the declaration rather than to a rewrite of
	// it. Run spdx.Canonicalize to compare it against detection.
	License string `json:"license"`
	// Path names the license file the declaration describes, when it describes
	// one. A declaration with no path speaks for the component as a whole.
	Path string `json:"path,omitempty"`
	// Override records a classification the declaration knowingly disagrees
	// with, so that a difference somebody has already reviewed stops being
	// reported as new. It holds the identifier the classifier is expected to
	// produce, and stops applying the moment the classifier produces a
	// different one.
	Override string `json:"override,omitempty"`
}

type Discovery struct {
	// Candidates are the discovered license files, ordered by descending
	// weight with ties broken by path.
	Candidates []Candidate
	// Unreadable are the paths the scan could not read or descend into.
	//
	// They are reported rather than fatal, because a tree with one unreadable
	// directory still has evidence in the rest of it - but they are reported
	// rather than ignored, because a component that appears to have no license
	// and a component whose license directory could not be read mean opposite
	// things.
	Unreadable []string
}

type ExclusionReason string

type File struct {
	// Path is the file's path within the scanned filesystem.
	Path string `json:"path"`
	// Weight is the filename-based relevance from discovery, carried so that
	// whatever weighs candidates later weighs them as discovery did.
	Weight float64 `json:"weight"`
	// Excluded says why the file is not evidence about this component, and is
	// empty for a file that is.
	Excluded ExclusionReason `json:"excluded,omitempty"`
	// License is the classifier's own name for the strongest match, reported
	// verbatim, and NoAssertion when nothing matched. Normalize it through the
	// spdx package before comparing or publishing it.
	License string `json:"license"`
	// Confidence is the classifier's confidence in License.
	Confidence float64 `json:"confidence"`
	// AdditionalLicenses are the other licenses the classifier recognized in
	// the same file, strongest first.
	//
	// One file can carry two license texts - a LICENSE that appends a bundled
	// dependency's terms is the common shape - and they are two licenses. Only
	// reporting the strongest would settle such a component on one license and
	// hide the other, which is the direction of error that tells a consumer
	// they may ignore obligations they have.
	AdditionalLicenses []Match `json:"additional_licenses,omitempty"`
	// Declared is the license the caller declared for this file, when they
	// declared one, and Override the classification that declaration knowingly
	// disagrees with.
	Declared string `json:"declared,omitempty"`
	Override string `json:"override,omitempty"`
	// SizeBytes and Digest identify the whole file regardless of what Text
	// holds. The digest normalizes line endings; see contenthash for what that
	// means and why.
	SizeBytes int64  `json:"size_bytes"`
	Digest    string `json:"digest"`
	// Text is the retained license text, present only when the request asked
	// for it, and Truncated records that it is only the beginning of the file
	// so that a later non-match can be attributed to the bound rather than to
	// the text.
	Text      string `json:"text,omitempty"`
	Truncated bool   `json:"truncated,omitempty"`
	// Err records why this file could not be read or classified. The rest of
	// the result stands: one unreadable file is not a reason to discard the
	// evidence the others carry.
	Err string `json:"error,omitempty"`
}

type Grant struct {
	// Expression is the SPDX expression the notice states, suffix included.
	Expression string `json:"expression"`
	// Source is "spdx-tag" for a machine-readable SPDX-License-Identifier, or
	// "header" for a matched notice. The tag is exact; the header is a match.
	Source string `json:"source"`
	// Path locates the grant, and Files says how many sampled files agreed.
	Path  string `json:"path"`
	Files int    `json:"files"`
}

type GrantBasis string

type GrantEvidence struct {
	// Grants are the distinct grants stated, most-agreed first.
	Grants []Grant
	// Sampled is how many source files the grants were read from, which is
	// what Notices returns rather than how many it found. Zero means nobody
	// looked, which is a weaker claim than looking and finding none, so
	// counting a file that failed to open would settle a grant on no evidence.
	Sampled int
}

type HeaderMatch struct {
	Name       string
	Variant    string
	Confidence float64
}

type Match struct {
	// Name is the classifier's own name for the license, reported verbatim.
	// It is frequently not an SPDX identifier - the classifier emits names
	// that were never SPDX and names SPDX has deprecated - so nothing
	// downstream should compare or publish it without normalizing it through
	// the spdx package first.
	Name       string
	Confidence float64
}

type Notice struct {
	Path string `json:"path"`
	// Text is the first MaxNoticeBytes of the file.
	Text      string `json:"text"`
	Truncated bool   `json:"truncated,omitempty"`
}

type ProseHint struct {
	Path    string `json:"path"`
	Line    int    `json:"line"`
	Excerpt string `json:"excerpt"`
}

type Reason string

type Request struct {
	// FS is the tree to read. Callers scanning a directory should pass an
	// os.Root filesystem, so a symlink escaping the tree fails to resolve
	// rather than reading the host filesystem.
	FS fs.FS
	// Scope bounds discovery. The zero value, ScopeProject, looks for the
	// component's own license.
	Scope Scope
	// Declared are the licenses the caller already believes apply. A
	// declaration naming a path that discovery did not find is still read and
	// classified, since a component that keeps its license somewhere
	// unconventional is exactly the case a declaration exists to record.
	Declared []Declaration
	// RetainText keeps each classified text in the result, bounded by
	// MaxTextBytes, for a caller that has to persist evidence or classify it
	// again later. It is off by default: a build-time check has the tree in
	// front of it and needs no copy.
	//
	// Naming an unrecognized license needs it. A LicenseRef is a digest of the
	// license text, so Conclusion.UnrecognizedText fails without it rather than
	// naming the component something that reads as unlicensed.
	RetainText bool
	// Classifier identifies the texts. A nil Classifier uses a shared default
	// built once per process from the licenseclassifier corpus and Supplement.
	Classifier Classifier
}

type Result struct {
	// Files are the discovered license files, ordered by descending discovery
	// weight with ties broken by path.
	Files []File `json:"files"`
	// Unreadable are the paths the scan could not read or descend into, so that
	// a tree with no license evidence stays distinguishable from one that could
	// not be read to the end.
	Unreadable []string `json:"unreadable,omitempty"`
	// Notes carry caveats about the completeness of the result: texts truncated
	// at the bound, declarations naming a file that is not there. They describe
	// the collection, never the licensing.
	Notes []string `json:"notes,omitempty"`
}

type Scope int