contractgen

type CodegenArtifact struct {
	// Path is the repo-relative target path,
	// e.g. "generated/contracts/http/order/create/v1/types_gen.go".
	Path string
	// Content is the rendered, formatted, goimports-processed bytes.
	Content []byte
}

type CommandSpec struct {
	// DispatchID is the contract id used as the command.Registry key const,
	// e.g. "command.devicecommand.enqueue.v1".
	DispatchID string
	// HandlerMethod is the method name on the generated Handler interface:
	// "Handle" + goPascalCase(domainLastSegment(id)).
	// Example: for "command.synth.do.v1" → "HandleDo".
	HandlerMethod string
	// RequestGoType is the Go type name for the command request DTO.
	// Always "Request" (the generated DTO from types_gen.go); held as a field
	// so command.tmpl has a single source rather than a hardcoded literal.
	RequestGoType string
	// ResponseGoType is the Go type name for the command response DTO.
	// Always "Response".
	ResponseGoType string
}

type ContractGenSpec struct {
	// PackageName is the Go package name derived from the last path segment
	// of PackagePath (e.g. "create", "get", "ordercreated").
	PackageName string
	// PackagePath is the module-relative path for the generated package,
	// e.g. "generated/contracts/http/order/create/v1".
	PackagePath string
	// ContractID is the full contract id, e.g. "http.order.create.v1".
	ContractID string
	// Kind is one of the closed set: "http", "event", "command", "projection",
	// "webhook", "grpc", "saga".
	Kind string
	// Transports is the non-empty, parser-derived set of sanctioned wire
	// transports for this contract (#1389). The generated ContractSpec.Transport
	// is the primary, Transports[0]; templates render it uniformly across kinds
	// (spec.tmpl for events, handler.tmpl for http) so "generated Transport ==
	// transports[0]" has no kind special-case. For a multi-transport contract
	// (len > 1, e.g. an event over [amqp, mqtt]) spec.tmpl additionally emits an
	// exported `Transports` var so out-of-band subscribers reference the contract
	// truth source instead of hand-writing a transport string.
	Transports []string
	// ConsistencyLevel is the contract's declared consistency level ("L0".."L4").
	// Consumed by types.tmpl for two kinds, each driving a compile-time level
	// guard `const _ = uint(cellvocab.<ConsistencyLevel> - cellvocab.<floor>)`
	// that fails to compile when the level is below the floor:
	//   - kind=projection → floor L3 (PROJECTION-CONSISTENCY-01, gh #960)
	//   - kind=command    → floor L1 (COMMAND-CONTRACT-CONSISTENCY-LEVEL-01, #1668)
	// buildContractSpec validates that the value parses (cellvocab.ParseLevel)
	// before it reaches the template (validateProjectionLevel / validateCommandLevel).
	ConsistencyLevel string
	// SourceFile is the repo-relative path of the contract.yaml that drove
	// generation, e.g. "examples/todoorder/contracts/http/order/create/v1/contract.yaml".
	SourceFile string
	// DTOs holds the flattened list of Go struct definitions (nested types
	// expanded to top-level entries). Template iterates this slice directly.
	DTOs []DTOSpec
	// Endpoint is non-nil when Kind == "http". Its type is the unexported
	// httpEndpointSpec (sealed): no out-of-package code can construct a non-nil
	// Endpoint. The whole ContractGenSpec is also never handed to another
	// package as a mutable value — its sole constructor buildContractSpec and
	// every render wrapper are package-private (only Generate /
	// RenderContractArtifacts are exported, and those return rendered []byte,
	// never the spec). So neither constructing nor mutating an
	// FMT-34-unvalidated Endpoint to drive handler.tmpl is expressible from
	// another package. See httpEndpointSpec's godoc.
	Endpoint *httpEndpointSpec
	// Event is non-nil when Kind == "event".
	Event *EventEndpointSpec
	// Saga is non-nil when Kind == "saga". It drives saga.tmpl (the typed
	// Impl interface + BuildDefinition/Register); the step output DTOs it
	// references are emitted into DTOs (rendered by types.tmpl) like any kind.
	Saga *SagaSpec
	// Command is non-nil when Kind == "command". It drives command.tmpl (the
	// typed Handler interface + Register + Dispatch). Request/Response DTOs
	// are generated into DTOs (rendered by types.tmpl) like any kind.
	// iface_gen.go is NOT emitted for command (Handler lives in command_gen.go).
	Command *CommandSpec
	// (No grpc field: kind=grpc emits zero contractgen artifacts since #1688 —
	// buf's generated pb.<Svc>Server is the sole server contract.)
	// RequestSchemaJSON is the raw JSON content of the request schema file,
	// compacted to a single line (no extra whitespace).
	// Non-empty only when Kind=="http" and the contract declares schemaRefs.request.
	// The generated handler embeds this as a Go string literal to compile the
	// validator at construction time — no runtime file I/O, no embed.FS.
	// Empty string means no schema validation is emitted.
	RequestSchemaJSON string

	// PanicReasonPolicyNil is the kebab-case reason literal passed to
	// panicregister.Approved for the "policy must not be nil" panic site.
	// Pre-computed from ContractID (dots replaced by dashes) + "-policy-nil".
	// Example: "http-order-create-v1-policy-nil".
	PanicReasonPolicyNil string
	// PanicReasonBootstrapAuthNil is the kebab-case reason literal passed to
	// panicregister.Approved for the "bootstrapAuth must not be nil" panic site.
	// Pre-computed from ContractID + "-bootstrap-auth-nil".
	// Example: "http-sample-bootstrap-v1-bootstrap-auth-nil".
	PanicReasonBootstrapAuthNil string
	// PanicReasonPublicSchemaCompileFailed is the kebab-case reason literal passed
	// to panicregister.Approved for the schema compile failed panic in NewPublicHandler.
	// Pre-computed from ContractID + "-public-schema-compile-failed".
	// Example: "http-order-create-v1-public-schema-compile-failed".
	PanicReasonPublicSchemaCompileFailed string
	// PanicReasonBootstrapSchemaCompileFailed is the kebab-case reason literal passed
	// to panicregister.Approved for the schema compile failed panic in NewBootstrapHandler.
	// Pre-computed from ContractID + "-bootstrap-schema-compile-failed".
	// Example: "http-auth-setup-admin-v1-bootstrap-schema-compile-failed".
	PanicReasonBootstrapSchemaCompileFailed string
	// PanicReasonClientsOnlySchemaCompileFailed is the kebab-case reason literal passed
	// to panicregister.Approved for the schema compile failed panic in NewClientsOnlyHandler.
	// Pre-computed from ContractID + "-clients-only-schema-compile-failed".
	// Example: "http-config-flags-evaluate-v1-clients-only-schema-compile-failed".
	PanicReasonClientsOnlySchemaCompileFailed string
	// PanicReasonServiceOwnedSchemaCompileFailed is the kebab-case reason literal passed
	// to panicregister.Approved for the schema compile failed panic in NewServiceOwnedHandler.
	// Pre-computed from ContractID + "-service-owned-schema-compile-failed".
	// Example: "http-auth-session-delete-v1-service-owned-schema-compile-failed".
	PanicReasonServiceOwnedSchemaCompileFailed string
	// PanicReasonStandardSchemaCompileFailed is the kebab-case reason literal passed
	// to panicregister.Approved for the schema compile failed panic in the standard
	// NewHandler (with policy parameter).
	// Pre-computed from ContractID + "-standard-schema-compile-failed".
	// Example: "http-order-create-v1-standard-schema-compile-failed".
	PanicReasonStandardSchemaCompileFailed string
}

type DTOField struct {
	// Name is the PascalCase Go field name.
	Name string
	// JSONTag is the JSON tag value, e.g. "item,omitempty".
	JSONTag string
	// GoType is the Go type expression, e.g. "string", "int64", "*ResponseData".
	GoType string
	// Required indicates whether the field is in the schema's required list.
	Required bool
	// Doc is an optional comment, used for format hints (uuid, date-time).
	Doc string
	// Source identifies where this field originates: "body", "path", "query", or
	// "header". Empty means body (legacy/default). Only body fields receive schema
	// validation in the generated handler; path/query fields are validated at parse
	// time. "header" fields are populate-only (read from r.Header.Get, no gate) and
	// carry JSONTag "-" so the request body can never spoof them.
	Source string
	// MinLength constrains string body fields (minimum character length).
	MinLength *int
	// MaxLength constrains string body fields (maximum character length).
	MaxLength *int
	// Minimum constrains integer body fields (inclusive lower bound).
	Minimum *int64
	// Maximum constrains integer body fields (inclusive upper bound).
	Maximum *int64
}

type DTOSpec struct {
	// Name is the PascalCase struct name, e.g. Request, Response, Payload.
	Name string
	// Doc is the human-readable description (from schema.title).
	Doc string
	// Fields lists the struct fields in source-declared order.
	Fields []DTOField
	// Nested holds intermediate nested-object types discovered during schema
	// traversal. Callers of buildContractSpec see an empty slice — the builder
	// promotes nested types to ContractGenSpec.DTOs and clears this field.
	Nested []DTOSpec
}

type EventEndpointSpec struct {
	// Topic is the broker topic name (contract id with version suffix stripped),
	// e.g. "event.order-created".
	Topic string
	// HandlerMethod is the PascalCase handler method name,
	// e.g. "HandleOrderCreated".
	HandlerMethod string
	// Replayable indicates whether this event supports replay.
	Replayable bool
	// DeliverySemantics is the declared delivery guarantee, e.g. "at-least-once".
	DeliverySemantics string
}

type Options struct {
	// DryRun emits ActionWouldWrite without filesystem mutation.
	DryRun bool
	// Verify diffs the rendered content against disk and reports drift.
	// Mutually exclusive with DryRun at the CLI layer; combining them here
	// is harmless — Verify dominates (no write either way).
	Verify bool
	// Scope controls which contracts are processed. When nil, Generate returns
	// an error (fail-fast). Use ScopeAll{} for the default "all Codegen=true"
	// behavior, ScopeContracts for a specific ID list, or ScopeCell to restrict
	// to one cell's contracts.
	Scope Scope
	// ModulePath is the consuming repo's Go module path (from its go.mod),
	// threaded to the formatter so generated files group module-local imports
	// the way the target repo's golangci-lint gate expects (#1083). Required:
	// Generate rejects an empty ModulePath. The CLI resolves it via
	// resolveModule (flag-or-go.mod); RenderContractArtifacts resolves it from
	// root itself.
	ModulePath string
}

type PaginationShape struct {
	HasCursor        bool
	HasLimit         bool
	ExtraQueryParams []ParamSpec
}

type ParamSpec struct {
	// Name is the parameter name as declared in contract.yaml, e.g. "id", "cursor".
	Name string
	// GoName is the PascalCase Go field name used in the Request struct.
	GoName string
	// GoType is the Go scalar type: "string", "int64", "float64", or "bool".
	GoType string
	// Required is true for path params (always) or explicitly-required query params.
	Required bool
	// Doc is an optional hint comment.
	Doc string
	// Format is the json-schema format for this param, e.g. "uuid", "date-time".
	// Used by handler.tmpl to emit httputil.ParseUUIDPathParam for uuid-format path params.
	Format string
	// MinLength applies to string params.
	MinLength *int
	// MaxLength applies to string params.
	MaxLength *int
	// Minimum applies to numeric params.
	Minimum *int64
	// Maximum applies to numeric params.
	Maximum *int64
}

type ProtoMethodInfo struct {
	// Name is the rpc method name, e.g. "IssueCommand".
	Name string
	// RequestType is the request message simple name, e.g. "IssueCommandRequest".
	RequestType string
	// ResponseType is the response message simple name, e.g. "IssueCommandResponse".
	ResponseType string
}

type ProtoServiceInfo struct {
	// ProtoPackage is the proto `package` declaration, e.g. "device.command.v1".
	ProtoPackage string
	// ImportPath is the go_package import path (the part before ';'),
	// e.g. "github.com/ghbvf/gocell/generated/contracts/grpc/device/command/v1".
	ImportPath string
	// Alias is the go_package import alias (the part after ';'), e.g. "commandv1".
	Alias string
	// Methods lists every unary RPC in the service block; streaming RPCs and
	// unexported-identifier method names are rejected (see parseAllRPCMethods).
	Methods []ProtoMethodInfo
}

type ResponseSpec struct {
	// Status is the HTTP status code, e.g. 200, 204, 401, 503.
	Status int
	// Description mirrors the contract.yaml response description (free form).
	// Empty for the success entry (the success body schema documents itself).
	Description string
	// SchemaRef is the contract-relative path to the JSON schema that
	// describes this response body. Empty for the success entry (success
	// body lives in schemaRefs.response, not in responses[]) and for the
	// 204 NoContent entry.
	SchemaRef string
	// IsError is true for status >= 400; the success entry is false.
	IsError bool
	// IsNoContent is true for the 204 NoContent success entry — the
	// generated typed struct is an empty marker (`struct{}`) and the visit
	// method writes only the status header. Templates branch on this flag
	// rather than reverse-derive the suffix from GoTypeName, keeping the
	// IR the single source for the JSON-vs-NoContent distinction.
	IsNoContent bool
	// GoTypeName is the Go identifier for the typed response struct that
	// implements the per-endpoint XxxResponseObject interface. The naming
	// convention is {HandlerMethod}{Status}{Suffix}: 200 → 200JSONResponse,
	// 204 → 204NoContentResponse, 4xx/5xx → {Status}ErrorResponse.
	GoTypeName string
}

type Result struct {
	// Generated lists files that were written, would-have-been-written
	// (DryRun), or remain unchanged (Unchanged).
	Generated []string
	// Drifted lists files whose disk content differs from the freshly
	// rendered content (Verify mode only).
	Drifted []string
}

type RetryPolicySpec struct {
	MaxAttempts      int
	BaseIntervalExpr string
	MaxIntervalExpr  string
}

type SagaSpec struct {
	// DefinitionID is the contract id, used as the saga.Definition.ID const,
	// e.g. "saga.orderfulfillment.v1".
	DefinitionID string
	// TimeoutExpr is the Go duration expression for the saga-wide Timeout, e.g.
	// "30 * time.Second". Empty means the field is omitted (zero => no ceiling).
	TimeoutExpr string
	// RetryPolicy is the saga-wide default retry policy; nil means omit.
	RetryPolicy *RetryPolicySpec
	// CompensationOrder is the validated compensation walk order; always
	// "reverse" today (informational — the runtime owns the reverse walk).
	CompensationOrder string
	// NeedsTime reports whether any duration expr is present, so saga.tmpl
	// imports the time package only when used.
	NeedsTime bool
	// Steps are the forward steps in execution order.
	Steps []SagaStepSpec
}

type SagaStepSpec struct {
	// Name is the raw SafeID step name literal, e.g. "reserveInventory".
	Name string
	// GoName is goPascalCase(Name), e.g. "ReserveInventory".
	GoName string
	// OutputGoType is the typed output struct name, goPascalCase(Name)+"Output".
	OutputGoType string
	// InputGoType is the previous step's OutputGoType; empty when IsFirst.
	InputGoType string
	// IsFirst marks step 0 (its Run takes no typed input).
	IsFirst bool
	// HasCompensate is true when the step declares compensation (default true);
	// only then is a Compensate method emitted on Impl + a non-nil
	// saga.Step.Compensate wired.
	HasCompensate bool
	// TimeoutExpr is the Go duration expression for the per-step Timeout; empty
	// means omit (inherit Definition.Timeout).
	TimeoutExpr string
	// RetryPolicy overrides the saga-wide policy for this step; nil means omit.
	RetryPolicy *RetryPolicySpec
}

type Schema struct {
	Type                 string             // "string" | "integer" | "number" | "boolean" | "object" | "array"
	Format               string             // "uuid" | "date-time" | "int64" | ""
	Properties           map[string]*Schema // type=object
	PropertyOrder        []string           // source order of property keys
	Required             []string           // type=object
	Items                *Schema            // type=array
	Ref                  string             // "$ref" original value (preserved for traceability)
	AdditionalProperties bool               // bool only; schema form is unsupported (true = JSON Schema default)
	Title                string
	MinLength            *int   // type=string; pointer distinguishes 0 from unset
	MaxLength            *int   // type=string
	Minimum              *int64 // numeric types
	Maximum              *int64
	SourcePath           string // file path + JSON pointer for error messages
}

type Scope interface {
	// contains filtered or unexported methods
}

type ScopeAll struct{}

type ScopeCell string

type ScopeContracts []string