schemadef

type CanonicalType string

type CheckConstraint struct {
	// Name is the constraint name — postgres auto-derives one
	// (`<table>_<col>_check`, `_check1`, …) for CHECKs written inline
	// without an explicit CONSTRAINT name, which is how forge emits them.
	Name string
	// Def is the canonical constraint definition from
	// pg_get_constraintdef, e.g. "CHECK (amount_cents >= 0)" or
	// "CHECK (status = ANY (ARRAY['A'::text, 'B'::text]))".
	Def string
	// Columns are the column names the check references (its conkey),
	// in key order. Single-column for every check forge itself projects
	// (enum vocabulary, protovalidate bounds, the id-non-empty guard).
	Columns []string
}

type Column struct {
	Name string
	// DeclType is the declared SQL type verbatim from the migration
	// (e.g. "TIMESTAMPTZ", "TEXT[]", "DOUBLE PRECISION").
	DeclType string
	// Type is the canonical forge type the declared type maps to.
	Type CanonicalType
	// IsArray is true for declared array types ("TEXT[]"); Type then
	// holds the ELEMENT type.
	IsArray bool
	// TypeKnown is false when DeclType matched no arm of the mapping
	// table — MONEY, INET, INTERVAL, TSVECTOR, a native pg enum. Type is
	// then TypeString as a fallback, NOT as a mapping, and anything that
	// projects a wire contract from this column must say so rather than
	// publish a `string` field postgres will reject writes to.
	TypeKnown bool
	// MaxChars is the declared character cap of a varchar(n)/char(n) column,
	// 0 when the type is unbounded. DeclType cannot carry it: it is rebuilt
	// from udt_name, which spells both `varchar` and `varchar(4)` as
	// "VARCHAR". Anything that must not overflow the column (seed synthesis,
	// generated test fixtures) reads this.
	MaxChars int
	NotNull  bool
	// Default is the raw default expression, "" when none.
	Default string
	IsPK    bool
	// IsGenerated is true for GENERATED ALWAYS AS (...) STORED columns —
	// the database computes them, so they must never be written on
	// INSERT/UPDATE (postgres rejects writes to generated columns).
	IsGenerated bool
	// Comment is the column's catalog comment (COMMENT ON COLUMN), "" when
	// none. It carries the `forge:*` column declarations the same way a
	// constraint comment carries `forge:ref` — plain SQL, applied by the
	// migration, landing in the postgres catalog where forge, `psql \d+` and
	// anything else can read it. Only the `forge:` clause is interpreted;
	// prose in the same comment is fine.
	Comment string
}

type Conventions struct {
	SoftDelete bool
	Timestamps bool
	// AppendOnly mirrors Table.AppendOnly (a COMMENT ON TABLE
	// `forge:append-only` declaration). Unlike the two above it is a
	// DECLARATION rather than a column-shape convention — no arrangement of
	// columns can express "this table refuses UPDATE" — but it rides here
	// because every consumer of behavior-by-table already reads
	// Conventions, and a second channel is how one pass ends up honouring
	// what another ignores.
	AppendOnly bool
	// SearchColumns are the text columns (excluding the PK and managed
	// columns) the generated search filter matches against.
	SearchColumns []string
}

type ForeignKey struct {
	Column    string
	RefTable  string
	RefColumn string
	// Name is the constraint name postgres knows it by — explicit
	// (`CONSTRAINT orders_patient_id_fkey`) or auto-derived from an inline
	// REFERENCES. It is what a COMMENT ON CONSTRAINT statement names.
	Name string
	// OnDelete is the referential action as information_schema spells it:
	// "NO ACTION" (postgres's default), "RESTRICT", "CASCADE", "SET NULL"
	// or "SET DEFAULT".
	//
	// It is a behaviour of the reference, not a decoration on it: CASCADE
	// means deleting the parent silently deletes these rows. Anything
	// reporting that a reference exists without saying what it does on
	// delete has described the cheap half.
	OnDelete string
	// Comment is the constraint's catalog comment (COMMENT ON CONSTRAINT
	// ... IS '...'), "" when none. It is where a project DECLARES a domain
	// fact about the reference that the schema alone cannot express — see
	// seeddata's diamond resolution. Read from the applied catalog, never
	// from migration text, so there is one source of truth.
	Comment string
}

type Index struct {
	Name    string
	Columns []string
	Unique  bool
	// Predicate is the WHERE clause of a PARTIAL index, "" for a full one.
	//
	// It is load-bearing for a UNIQUE index and cannot be dropped: a
	// partial `UNIQUE (email) WHERE deleted_at IS NULL` permits duplicate
	// emails among soft-deleted rows, and reporting it as plain
	// `UNIQUE (email)` describes a stricter table than the one that
	// exists. An unqualified claim is worse than no claim.
	Predicate string
	// Expression is true when at least one index key is an EXPRESSION
	// rather than a bare column — `UNIQUE (lower(name))`,
	// `UNIQUE (supplier_id, lower(sku))`.
	//
	// It exists because such an index cannot be described by Columns
	// alone, and describing it partially is worse than not describing it.
	// pg_catalog stores an expression key as attnum 0, which carries no
	// pg_attribute row, so a column-joining introspection query drops that
	// key silently: `UNIQUE (lower(name))` came back as an index with NO
	// columns, and `UNIQUE (supplier_id, lower(sku))` came back as
	// `UNIQUE (supplier_id)` — a DIFFERENT, stricter constraint than the
	// one the table has.
	//
	// Columns holds only the bare-column subset, so it must never be read
	// as the whole key: `lower(name)` being unique does not make `name`
	// unique, and `(supplier_id, lower(sku))` being unique does not make
	// `supplier_id` unique. Read Keys for the full key, in order.
	Expression bool
	// Keys is every index key in order, as postgres renders it: a bare
	// column is its name, an expression key is its SQL text
	// (`lower(name)`). It is the only faithful description of an
	// expression index, and it is what lets a consumer recognise the
	// common case-insensitive form and plan against the underlying column
	// instead of giving up on the index entirely.
	//
	// Populated for every index by introspection. A hand-constructed Index
	// may leave it nil, so read it through [Index.KeyList], which falls
	// back to Columns.
	Keys []IndexKey
}

type IndexKey struct {
	// Expr is the key as postgres renders it: "name" for a bare column,
	// "lower(name)" for an expression.
	Expr string
	// Column is the bare column this key is over, when that is knowable:
	// the column itself for a plain key, and the argument for a
	// single-column case fold like `lower(name)`. Empty when the key spans
	// several columns or uses an expression this package does not read
	// (`(a || b)`, `(meta->>'k')`).
	//
	// A consumer that can only place a value for a real column uses this
	// to decide whether the key is reachable at all.
	Column string
	// Fold names the case-folding function wrapping Column — "lower" or
	// "upper" — and is empty for every other key, including a plain one.
	//
	// This is the one expression form worth reading rather than refusing.
	// `UNIQUE (lower(email))` is how case-insensitive uniqueness is
	// spelled in postgres and is common in hand-written migrations, and
	// its rule is exactly "these values must be distinct ignoring case" —
	// which a value generator CAN satisfy without evaluating SQL.
	Fold string
}

type Queryer interface {
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
}

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

type Table struct {
	Name string
	// Schema is the postgres schema the table lives in ("public",
	// "controlplane", …). Tables are still keyed by Name; Schema exists so SQL
	// forge emits against the shadow can address the table when its schema is
	// not on the connection's search_path.
	Schema  string
	Columns []Column
	// Comment is the table's catalog comment (COMMENT ON TABLE), "" when
	// none. It is where a TABLE-level `forge:*` declaration lives, the twin
	// of Column.Comment one level up.
	Comment string
	// Triggers lists the table's trigger names, sorted. It exists because a
	// declaration forge started writing at some release is absent from
	// every table born before it, and a table's ENFORCEMENT outlives the
	// release that wrote it: AppendOnly reads the guard trigger as a
	// second, older declaration of the same fact. See appendOnlyGuardTrigger.
	Triggers []string
	// PKCols lists primary-key column names in key order.
	PKCols []string
	// Indexes lists non-PK indexes (unique and plain).
	Indexes []Index
	// ForeignKeys lists declared REFERENCES constraints.
	ForeignKeys []ForeignKey
	// Checks lists the table's CHECK constraints, read back through
	// postgres's own catalog (pg_get_constraintdef). Because both the
	// applied migration dir and any freshly-projected DDL are introspected
	// through the SAME catalog, two semantically-identical CHECKs — however
	// they were spelled in the source SQL (`col IN (...)` vs the postgres
	// `col = ANY (ARRAY[...])` normal form) — read back byte-identical here.
	// That is what lets a drift comparison diff CHECK vocabulary reliably
	// without re-implementing postgres's expression normalizer.
	Checks []CheckConstraint
}