mcp

type ActionableSection struct {
	Count    int    `json:"count"`
	Withheld int    `json:"withheld"`
	Note     string `json:"note,omitempty"`
	// Endpoints is the rendered prefix of the ranked list: hardest gap kind first
	// (affirmed → access → exposure → efficiency), then by certain-concern count.
	Endpoints []report.ActionableEndpoint `json:"endpoints,omitempty"`
}

type BaselineAcceptRequest struct {
	Root         string   `json:"root"`
	Fingerprints []string `json:"fingerprints"`
	Reason       string   `json:"reason"`
}

type BaselineAcceptResponse struct {
	Accepted []string `json:"accepted"`
	Note     string   `json:"note"`
}

type BaselineDelta struct {
	New               int        `json:"new"`
	Changed           int        `json:"changed"`
	Known             int        `json:"known"`
	Acknowledged      int        `json:"acknowledged"`
	Gone              int        `json:"gone"`
	AffirmationsShown int        `json:"affirmations_shown"`
	GoneCandidates    []GoneItem `json:"gone_candidates,omitempty"`
	Note              string     `json:"note"`
}

type BaselineListRequest struct {
	Root     string `json:"root"`
	Language string `json:"language,omitempty"`
	Filter   string `json:"filter,omitempty"`
}

type BaselineListResponse struct {
	Items        []baseline.Entry       `json:"items"`
	Count        int                    `json:"count"`
	AuthzHelpers []baseline.AuthzHelper `json:"authz_helpers,omitempty"`
	Note         string                 `json:"note"`
}

type BaselinePruneRequest struct {
	Root         string   `json:"root"`
	Language     string   `json:"language"`
	Fingerprints []string `json:"fingerprints,omitempty"`
}

type BaselinePruneResponse struct {
	Pruned []string `json:"pruned"`
	Note   string   `json:"note"`
}

type BaselineRegisterAuthzHelperRequest struct {
	Root       string `json:"root"`
	Language   string `json:"language"`
	HelperName string `json:"helper_name"`
	Reason     string `json:"reason"`
}

type BaselineRegisterAuthzHelperResponse struct {
	Registered bool   `json:"registered"`
	Note       string `json:"note"`
}

type BaselineUnregisterAuthzHelperRequest struct {
	Root       string `json:"root"`
	Language   string `json:"language"`
	HelperName string `json:"helper_name"`
}

type BaselineUnregisterAuthzHelperResponse struct {
	Unregistered bool   `json:"unregistered"`
	Note         string `json:"note"`
}

type BudgetBlock struct {
	Bytes    int    `json:"bytes"`
	Withheld int    `json:"withheld"`
	Ordering string `json:"ordering"`
	Note     string `json:"note"`
}

type CheckCVEsRequest struct {
	Root string `json:"root"`
}

type CheckCVEsResponse struct {
	Vulnerable          []VulnerableDependency `json:"vulnerable"`
	DependenciesScanned int                    `json:"dependencies_scanned"`
	Notes               []string               `json:"notes"`
}

type ConfirmSurfaceRequest struct {
	Confirmations []surface.Confirmation `json:"confirmations"`
}

type ConfirmSurfaceResponse struct {
	Findings  []findings.Finding     `json:"findings"`
	Dismissed []surface.Confirmation `json:"dismissed"`
	Uncertain []surface.Confirmation `json:"uncertain"`
	Invalid   []surface.Confirmation `json:"invalid"`
}

type CoverageRequest struct {
	Language string `json:"language"`
	// Detail names the entries whose full prose the caller wants. Many ids in
	// one call: an agent that has to make one round trip per declared limit
	// stops asking. Omit it and the answer is the index alone.
	Detail []string `json:"detail,omitempty"`
}

type CoverageResponse struct {
	Language string `json:"language"`
	// Index holds EVERY entry the manifest carries, always. The response budget
	// authorizes withholding for scan-all; for coverage it authorizes nothing,
	// so an over-budget index is reported as over budget and stays complete.
	Index []coverage.IndexEntry `json:"index"`
	// Entries, Bytes and IndexBytes let the caller check the facts it would
	// otherwise have to take on trust: how many entries arrived, and how large
	// this response's payload was on the wire.
	//
	// Bytes is the WHOLE payload — the index plus any detail that was asked for
	// — and never the index alone. It used to be the index alone, which made a
	// detail request answer with a size verdict scoped to something smaller than
	// what it was returning: a 182,440-byte response declaring 21,951 bytes and
	// "within budget". A response that misreports its own size is the defect
	// PR #128 fixed for scan-all's budget note, and it is not allowed here either.
	Entries    int `json:"entries"`
	Bytes      int `json:"bytes"`
	IndexBytes int `json:"index_bytes"`
	// Withheld is always zero, and WithheldNote says so in words. "No mention of
	// truncation" and "nothing was truncated" are not the same bytes, and an
	// agent cannot tell a complete answer from a quiet one without being told.
	Withheld     int    `json:"withheld"`
	WithheldNote string `json:"withheld_note"`
	// OverBudget reports that the index exceeded the response budget. Nothing is
	// dropped when it does — the instruction is to shorten a claim.
	OverBudget bool   `json:"over_budget,omitempty"`
	BudgetNote string `json:"budget_note,omitempty"`
	// Detail carries the full prose of the requested entries, byte for byte as
	// authored.
	Detail []coverage.Entry `json:"detail,omitempty"`
	// Unrecognized names every requested id that matched no entry. Naming it is
	// the point: an empty success would say the entry has nothing to declare,
	// which is a different and false answer from "there is no such entry".
	Unrecognized     []string `json:"unrecognized,omitempty"`
	UnrecognizedNote string   `json:"unrecognized_note,omitempty"`
	// Derived is true when the answer was COMPUTED from the provider's
	// Capability() rather than served from a hand-written CoverageManifest()
	// (R1, docs/specs/declared-partial-language-exposure.md): the derived
	// answer is the FLOOR every registered, exposed language gets; a
	// hand-written prose manifest (TypeScript today) stays authoritative and
	// is never replaced by this.
	Derived bool `json:"derived"`
}

type DBSection struct {
	Measured bool                 `json:"measured"`
	Note     string               `json:"note,omitempty"`
	Findings []findings.Finding   `json:"findings,omitempty"`
	Surface  []surfaceindex.Entry `json:"surface,omitempty"`
	// Count is the COMPLETE number of surface items this section classifies —
	// taken from surfaceindex.Index's own return, computed independently of how
	// Surface is built, never from len(Surface) after the fact (design D4/I4:
	// reading it back off the rendered index is the self-referential trap the
	// coverage-chain archive records, obs #1664).
	Count int `json:"count"`
	// Withheld is always 0: there is no ranking axis across db surface's 18
	// disjoint categories (no severity field) to withhold BY — a stated absence
	// of a mechanism, not a principle (design D4). WithheldNote says so in
	// words, deliberately NOT coverage's sentence (a different reason) and NOT
	// the endpoint-bucket pattern (db.surface is never partially rendered).
	Withheld     int    `json:"withheld"`
	WithheldNote string `json:"withheld_note,omitempty"`
	Score        int    `json:"score"`
}

type DBSummary struct {
	SchemaSources         int `json:"schema_sources"`
	DeterministicFindings int `json:"deterministic_findings"`
	SurfaceItems          int `json:"surface_items"`
}

type FileInput struct {
	Path    string `json:"path"`
	Content string `json:"content"`
}

type FrontierPending struct {
	Count     int                       `json:"count"`
	Withheld  int                       `json:"withheld"`
	Note      string                    `json:"note,omitempty"`
	Endpoints []report.FrontierEndpoint `json:"endpoints,omitempty"`
}

type GoneItem struct {
	Fingerprint string `json:"fingerprint"`
	Category    string `json:"category"`
	File        string `json:"file"`
	Snippet     string `json:"snippet,omitempty"`
}

type ResolvedClean struct {
	Count     int                            `json:"count"`
	Withheld  int                            `json:"withheld"`
	Note      string                         `json:"note,omitempty"`
	Endpoints []report.ResolvedCleanEndpoint `json:"endpoints,omitempty"`
}

type ScanAllRequest struct {
	Root     string `json:"root"`
	Language string `json:"language"`
	// ChangedFiles narrows the audit to these project-relative paths (layer 0 of
	// the filtering pyramid). codefit does not ask git which files changed — it
	// has no power over the user's git, and the calling agent already knows what
	// it touched. Absent or empty means a FULL audit, never "audit nothing".
	//
	// A narrowed run declares itself in the response's scope block, cannot mark a
	// baseline item in an unopened file as gone, and leaves the DB dimension NOT
	// MEASURED unless a configured schema path is in scope.
	ChangedFiles []string `json:"changed_files,omitempty"`
}

type ScanAllResponse struct {
	// Summary is the per-dimension count block: one sub-block per audit
	// dimension plus a derived totals, each count declaring which dimension it
	// counted. A null sub-block means that dimension was not measured; see
	// ScanAllSummary for why an unqualified count was a defect.
	Summary ScanAllSummary `json:"summary"`
	// Scope declares how much of the project this response describes: mode full or
	// partial, how many auditable files were in scope, and which requested paths
	// the audit never reached. It is ALWAYS present, so a consumer never infers
	// the mode from an absence and never reads a partial `blocked: false` as the
	// wider claim it is not.
	Scope ScopeBlock `json:"scope"`
	// Score is the per-dimension breakdown plus the weighted global (ADR 0021). It
	// is ALWAYS present: by_dimension carries every weighted dimension, with the
	// unaudited ones (review/complexity/tests, and db when it did not run) as null —
	// an honest statement that the dimension exists but was not measured. The score
	// reflects deterministic AFFIRMATIONS only, not mapped surface.
	Score    scoring.ScoreSummary `json:"score"`
	Baseline BaselineDelta        `json:"baseline"`
	// Budget declares the response's own byte budget and whether anything was
	// withheld to meet it. ALWAYS present, including when nothing was withheld: an
	// agent must be able to tell a complete list from a cut one by reading the
	// response, never by guessing (ADR 0054).
	Budget          BudgetBlock       `json:"budget"`
	Actionable      ActionableSection `json:"actionable"`
	ResolvedClean   ResolvedClean     `json:"resolved_clean"`
	FrontierPending FrontierPending   `json:"frontier_pending"`
	// Security reports whether the security dimension ran (D3b). It is ALWAYS
	// present — deliberately NOT `omitempty`, unlike DB: the db dimension may
	// legitimately not apply to a project (no database configured), but security
	// applies to every project, so an ABSENT section could only mean an older
	// codefit build. Measured=false with a Note is the honest "no provider for
	// this language" state, mirroring DBSection's own Measured/Note shape.
	Security SecuritySection `json:"security"`
	// DB is the parallel database-structure section — the db dimension's findings
	// and surface, baseline-filtered. It is NON-endpoint (a table has no route), so
	// it is its own section, not one of the three endpoint buckets. Nil when the
	// project has no database.schema_paths configured, so a project without a
	// database yields a response byte-identical to before db was wired (ADR 0020).
	DB *DBSection `json:"db,omitempty"`
}

type ScanAllSummary struct {
	// Security counts the security dimension only. Nil when no provider
	// resolved for the language — never a zeroed block, which would read as
	// "codefit looked at the code and found nothing".
	Security *SecuritySummary `json:"security"`
	// DB counts the database dimension only. Nil when the dimension did not
	// run (no database.schema_paths configured, or narrowed out of scope) and
	// when it ran but could not measure (no parser, unreadable schema) — the
	// DBSection.Measured=false state.
	DB *DBSummary `json:"db"`
	// Totals is DERIVED from the non-nil sub-blocks, never written by hand: a
	// hand-kept total drifts the first time a dimension is added. It carries
	// only COMMENSURABLE units — a deterministic finding and a mapped surface
	// item mean the same thing in both dimensions. Endpoints and schema
	// sources are each dimension's own scale unit and are summed nowhere: a
	// table has no route.
	Totals SummaryTotals `json:"totals"`
	// Note is ALWAYS present, on the BudgetBlock precedent: "no mention" and
	// "nothing to mention" must not be the same bytes on the wire.
	Note string `json:"note"`
}

type ScanDBRequest struct {
	Root     string   `json:"root"`
	Language string   `json:"language"`
	Detail   []string `json:"detail,omitempty"`
}

type ScanDBResponse struct {
	Measured     bool                 `json:"measured"`
	Note         string               `json:"note,omitempty"`
	Findings     []findings.Finding   `json:"findings"`
	Surface      []surfaceindex.Entry `json:"surface"`
	Count        int                  `json:"count"`
	Withheld     int                  `json:"withheld"`
	WithheldNote string               `json:"withheld_note,omitempty"`
	Score        int                  `json:"score"`
	// Detail carries the full item for every requested id that matched, byte
	// for byte the pre-change flat Surface shape.
	Detail []findings.SurfaceItem `json:"detail,omitempty"`
	// Unrecognized names every requested id that matched nothing. Naming it is
	// the point: an empty success would say the item has nothing to declare,
	// which is a different and false answer from "there is no such item".
	Unrecognized     []string `json:"unrecognized,omitempty"`
	UnrecognizedNote string   `json:"unrecognized_note,omitempty"`
	// Bytes/IndexBytes/OverBudget/BudgetNote declare this response's own size,
	// wired only once Detail exists (design D5) — the exact shape that made
	// CoverageResponse under-declare its size before it carried Bytes/IndexBytes
	// (#1664, closed in S3): bytes is measured LAST, over index + detail.
	Bytes      int    `json:"bytes"`
	IndexBytes int    `json:"index_bytes"`
	OverBudget bool   `json:"over_budget,omitempty"`
	BudgetNote string `json:"budget_note,omitempty"`
}

type ScanEndpointRequest struct {
	Root     string `json:"root"`
	Language string `json:"language"`
	File     string `json:"file"`
}

type ScanEndpointResponse struct {
	File      string                  `json:"file"`
	Found     bool                    `json:"found"`
	Endpoints []report.EndpointReport `json:"endpoints,omitempty"`
	Note      string                  `json:"note,omitempty"`
}

type ScanRequest struct {
	Root     string `json:"root"`
	Language string `json:"language"`
	// ChangedFiles narrows the audit to these project-relative paths (layer 0 of
	// the filtering pyramid). codefit does not ask git which files changed — it
	// has no power over the user's git, and the calling agent already knows what
	// it touched. Absent or empty means a FULL audit, never "audit nothing", and
	// a narrowed run declares itself in the response's scope block.
	ChangedFiles []string `json:"changed_files,omitempty"`
}

type ScanResponse struct {
	Findings []findings.Finding     `json:"findings"`
	Surface  []findings.SurfaceItem `json:"surface"`
	Score    int                    `json:"score"`
	Blocked  bool                   `json:"blocked"`
	Scope    ScopeBlock             `json:"scope"`
	// SurfaceCoverage declares which of surface.ProviderCategories this
	// language's provider mapped and which it did not (R2,
	// docs/specs/declared-partial-language-exposure.md): a project whose
	// provider maps a narrow slice of the vocabulary (Go today: authz only)
	// must never report surface_items with no statement that the rest was
	// never searched for. ALWAYS present — HandleScanSecurity errors before
	// reaching this point when no provider resolves, so a returned response
	// always has one.
	SurfaceCoverage surface.CoverageStatement `json:"surface_coverage"`
}

type ScopeBlock struct {
	Mode           string   `json:"mode"`
	Requested      int      `json:"requested"`
	Audited        int      `json:"audited"`
	AuditableTotal int      `json:"auditable_total"`
	Unmatched      []string `json:"unmatched,omitempty"`
	Note           string   `json:"note"`
}

type SecuritySection struct {
	Measured bool   `json:"measured"`
	Note     string `json:"note,omitempty"`
	// SurfaceCoverage declares which of surface.ProviderCategories this
	// language's provider mapped and which it did not (R2,
	// docs/specs/declared-partial-language-exposure.md) — the "1 of 4"
	// statement a bare `surface_items: 1` never made. Present only when
	// Measured is true: a pointer, so a DB-only pass (Measured=false, no
	// provider resolved) serializes no surface_coverage key at all, rather
	// than a zero-valued statement that could be misread as "nothing
	// unmapped".
	SurfaceCoverage *surface.CoverageStatement `json:"surface_coverage,omitempty"`
}

type SecuritySummary struct {
	Endpoints             int `json:"endpoints"`
	DeterministicFindings int `json:"deterministic_findings"`
	SurfaceItems          int `json:"surface_items"`
	CertainConcerns       int `json:"certain_concerns"`
}

type SummaryTotals struct {
	DeterministicFindings int `json:"deterministic_findings"`
	SurfaceItems          int `json:"surface_items"`
}

type SurfaceIDORRequest struct {
	Files []FileInput `json:"files"`
}

type SurfaceResponse struct {
	Surface []findings.SurfaceItem `json:"surface"`
	// HelperScope is set ONLY by HandleSurfaceAuthz and HandleSurfaceIDOR: it
	// declares that their helper-dependent structural facts (known_authz_detected)
	// were computed against codefit's BUILT-IN helper set, never the project's
	// registered ones (ADR 0013). Like findings.SurfaceItem.StructuralFacts, this
	// is a FACT about what was computed, never a judgment about the result — a
	// false structural fact still means "not seen", not "unauthorized".
	// omitempty keeps it entirely ABSENT (not present-and-empty) on
	// HandleSurfaceOverfetch/HandleSurfaceNPlus1, whose facts never consult the
	// helper set: "no mention" and "nothing to mention" must not be the same
	// bytes.
	HelperScope string `json:"helper_scope,omitempty"`
}

type Tool string

type VulnerableDependency struct {
	Name            string              `json:"name"`
	Version         string              `json:"version"`
	Ecosystem       string              `json:"ecosystem"`
	Vulnerabilities []cve.Vulnerability `json:"vulnerabilities"`
}