contract

type ArtifactSnapshot map[string][]byte

type DefaultChain struct {
	Scope    string
	Name     string
	LogLevel string
}

type Deps struct{}

type File struct {
	Package string
	// Source is the base name of the file the interfaces were read from —
	// contract.go, or a package's deps.go — which mock_gen.go's header names
	// as the file to edit.
	Source  string
	Imports map[string]string // alias/name → import path (e.g. "sql" → "database/sql")
	// ExplicitImports records aliases that were written explicitly in
	// contract.go (for example `controlplanev1 ".../v1"`). Keeping that
	// bit lets the mock renderer preserve aliases whose spelling cannot be
	// recovered from the import path alone.
	ExplicitImports map[string]bool
	Interfaces      []InterfaceDef
	// InterfaceNames is the set of interface type names defined in this file.
	// Used by the zero-value generator to emit "nil" for interface-typed
	// returns instead of the invalid composite literal "T{}".
	InterfaceNames map[string]bool
	// PrimitiveAliases maps a named type (e.g. "BalanceCapReason") to its
	// underlying primitive kind (e.g. "string"). Populated by scanning
	// contract.go and its sibling .go files for `type X <primitive>`
	// declarations. Used by the zero-value generator to emit the
	// underlying primitive's zero (`""`, `0`, `false`) instead of the
	// invalid composite literal `BalanceCapReason{}`.
	PrimitiveAliases map[string]string
	// ForeignImports are import paths required by interfaces discovered
	// through the Deps struct rather than through contract.go. They are
	// held separately because collectImports only sees contract.go's own
	// import block, and a db.EstimateStore's signatures routinely mention
	// packages contract.go never imports (orm, the db package itself).
	ForeignImports map[string]ImportDef
}

type ImportDef struct {
	Path     string
	Name     string
	Explicit bool
}

type InterfaceDef struct {
	Name    string
	Methods []MethodDef
	// Qualifier is the package name to reach this interface by when it is
	// declared in ANOTHER package of the module (e.g. "db" for a
	// db.EstimateStore named in a Deps field). Empty for the ordinary
	// case: an interface declared in this package's own contract.go.
	//
	// The mock TYPE is always unqualified — MockEstimateStore, in the
	// consuming package — because the mock is generated here. Only the
	// compile-time check refers back to the original, as
	// `var _ db.EstimateStore = (*MockEstimateStore)(nil)`.
	Qualifier string
	// Collides is set when this foreign interface's bare name is also
	// declared locally, so MockName must disambiguate. See MockName.
	Collides bool
}

type MethodDef struct {
	Name    string
	Params  []ParamDef
	Results []ParamDef
	// SkipObserve is true when the interface method's doc / inline comment
	// carries the `// forge:no-observe` marker. The generated observability
	// decorator still wraps the type, but THIS method delegates DIRECTLY to the
	// inner implementation without routing through the observe chain. It is the
	// method-scoped twin of the package-level `// forge:no-observe` opt-out.
	SkipObserve bool
}

type Options struct {
	// ExtraInterfaceTypes is a project-supplied allow-list of cross-package
	// interface types the mock generator should treat as mockable. The
	// rendered type expression of a method's return (e.g.
	// "billing.MeterClient") is matched against this set during zero-value
	// emission; matches produce "nil" instead of the invalid composite
	// literal "T{}".
	//
	// Sourced from forge.yaml's `contracts.interface_types` at the CLI
	// layer; nil / empty is the no-op default.
	ExtraInterfaceTypes map[string]bool

	// ProjectRoot + Checksums route the mock write through the
	// checksums.WriteGeneratedFile chokepoint so the emitted
	// internal/<pkg>/mock_gen.go is recorded in the manifest AND in
	// the per-run WrittenThisRun set. Without this, the stale-artifact
	// sweep saw every manifest-tracked mock_gen.go as "tracked but not
	// re-emitted this run" and flagged it for deletion on every
	// `forge generate` — and the sweep would delete live mocks
	// (kalshi-trader FORGE_BACKLOG #15).
	//
	// ProjectRoot is the project root (the directory containing .forge/);
	// relative manifest paths are computed against it. Both fields nil
	// /empty preserve the legacy raw-os.WriteFile behavior for callers
	// without a manifest in scope (e.g. the `forge scaffold package` stub
	// emit — its mock is adopted into the manifest on the next full
	// generate).
	ProjectRoot string
	Checksums   *checksums.FileChecksums

	// Resolver answers what each import is called and what each foreign
	// Deps interface's method set is, from the Go toolchain. A caller
	// generating many contracts (the `forge generate` contracts step)
	// builds ONE with NewResolver over all of them, so the whole run costs
	// two go/packages loads. nil resolves this contract alone.
	Resolver *Resolver
}

type ParamDef struct {
	Name     string
	TypeExpr string // rendered Go type expression, e.g. "context.Context", "*sql.Rows", "...any"
	Variadic bool
}

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

type Retirement struct {
	// Retired lists artifacts removed from disk — provably forge's own
	// bytes, so nothing was lost.
	Retired []string
	// Kept lists artifacts left in place because forge could not prove
	// the bytes were its own. Callers should surface these: forge no
	// longer emits them, so only the user can resolve them.
	Kept []string
}

type Service interface {
	Generate(contractPath string) error
	ParseContract(path string) (*File, error)
}