control

package
v1.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 10, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package control implementa la maquinaria de cobertura, paridad y gating de la superapp de aceptación: el manifiesto de superficie pública, el reconciliador invocado-vs-manifiesto, la matriz de capacidad por motor y el reporte/gate.

Compila solo con la stdlib: no depende de la API de Quark, para poder razonarse y testearse de forma aislada.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Supports

func Supports(f Feature, e Engine) bool

Supports indica si el motor e soporta la feature f. Si devuelve false, el exerciser debe esperar quark.ErrUnsupportedFeature en ese motor.

Types

type Allowlist

type Allowlist struct {
	Reasons map[string]string `json:"reasons"` // Symbol.Key() -> motivo
}

Allowlist son los símbolos conscientemente fuera de scope, con justificación.

func LoadAllowlist

func LoadAllowlist(path string) (Allowlist, error)

LoadAllowlist lee allowlist.json. Si no existe, devuelve una allowlist vacía (sin justificaciones) junto al error, para que el caller decida.

func (Allowlist) Has

func (a Allowlist) Has(key string) bool

Has indica si key (Symbol.Key) está justificado fuera de scope.

type Cell

type Cell struct {
	Method string
	Engine Engine
	Status Status
	Detail string
}

Cell es una entrada de la matriz método × motor.

type Engine

type Engine string

Engine identifica cada motor soportado por Quark.

const (
	SQLite   Engine = "sqlite"
	Postgres Engine = "postgres"
	MySQL    Engine = "mysql"
	MariaDB  Engine = "mariadb"
	MSSQL    Engine = "mssql"
	Oracle   Engine = "oracle"
)

func AllEngines

func AllEngines() []Engine

AllEngines devuelve los 6 motores en orden estable.

type Feature

type Feature string

Feature nombra una capacidad que NO está disponible en todos los motores. Solo se listan las features con cobertura desigual; lo no listado se asume soportado en los 6.

const (
	FeatRLSNative     Feature = "rls_native"     // RLS forzada por el motor (set_config + CREATE POLICY)
	FeatListenNotify  Feature = "listen_notify"  // listener inbound LISTEN/NOTIFY
	FeatMigrationLock Feature = "migration_lock" // lock de migración distribuido
	FeatSkipLocked    Feature = "skip_locked"    // SELECT ... FOR UPDATE SKIP LOCKED

	// FeatSchemaPerTenant marca los motores con schemas reales dentro de una
	// base (CREATE SCHEMA + qualificación schema.table). A diferencia de las
	// features de arriba, Quark NO gatea esta estrategia con
	// ErrUnsupportedFeature (el builder emite el SQL cualificado y es el motor
	// quien lo acepta o no): en un motor no soportado el exerciser SALTA el
	// path funcional (SkippedExpected), no aserta un error. Fuente:
	// docs/playbooks/tenant.md ("sólo PG y MSSQL real, MySQL no tiene schemas").
	FeatSchemaPerTenant Feature = "schema_per_tenant"

	// FeatDBPerTenantProvision marca los motores donde el ARNÉS puede
	// aprovisionar una base de datos por tenant (la estrategia DatabasePerTenant
	// en sí es agnóstica del motor — sólo necesita DSNs distintos). SQLite usa
	// ficheros; PG/MySQL/MariaDB/MSSQL un CREATE DATABASE vía admin. Oracle
	// queda fuera: una "database" por tenant ahí es un PDB (operación
	// administrativa pesada, fuera del alcance del harness) y el equivalente
	// ligero (CREATE USER = schema) es la otra estrategia.
	FeatDBPerTenantProvision Feature = "db_per_tenant_provision"
)

type Invoked

type Invoked map[Engine]map[string]bool

Invoked registra qué símbolos se ejercieron en cada motor. Lo alimenta el recorder en runtime (paquete recorder/).

type Manifest

type Manifest struct {
	GeneratedAt *time.Time `json:"generated_at,omitempty"`
	Symbols     []Symbol   `json:"symbols"`
}

Manifest es el denominador: TODO lo que Quark expone. Lo genera cmd/gen-apisurface con go/packages — nunca se edita a mano.

GeneratedAt es un puntero con omitempty: el fichero versionado se genera SIN timestamp (determinista, para que un símbolo público nuevo produzca un diff limpio y CI pueda exigir regenerar). Sólo se rellena en corridas ad-hoc.

func LoadManifest

func LoadManifest(path string) (*Manifest, error)

LoadManifest lee apisurface.json.

func (*Manifest) Reconcile

func (m *Manifest) Reconcile(inv Invoked, allow Allowlist) []Cell

Reconcile compara el manifiesto contra lo invocado por motor y emite una celda MISSING por cada símbolo in-scope no ejercido en cada motor. No emite PASS/FAIL: eso lo deciden las aserciones funcionales de los exercisers.

type Report

type Report struct {
	Cells []Cell
}

Report acumula celdas y produce la matriz + el veredicto del gate.

func (*Report) Add

func (r *Report) Add(method string, e Engine, s Status, detail string)

Add registra una celda.

func (*Report) AddAll

func (r *Report) AddAll(cells []Cell)

AddAll agrega un lote de celdas (p.ej. la salida de Manifest.Reconcile).

func (*Report) Gate

func (r *Report) Gate(strict bool, allow Allowlist) error

Gate devuelve error si, en modo estricto, hay alguna celda FAIL o MISSING que no esté justificada en la allowlist. SkippedExpected y Passed nunca fallan.

func (*Report) Render

func (r *Report) Render(w io.Writer)

Render escribe la matriz método × motor en w.

type Status

type Status string

Status es el resultado de un par (método, motor).

const (
	StatusPassed          Status = "PASS"     // invocado y las aserciones funcionales pasaron
	StatusSkippedExpected Status = "SKIP-EXP" // motor sin la capacidad; devolvió el error esperado
	StatusFailed          Status = "FAIL"     // invocado pero una aserción falló
	StatusMissing         Status = "MISSING"  // en el manifiesto, nunca invocado en este motor
)

type Symbol

type Symbol struct {
	Pkg  string `json:"pkg"`  // p.ej. github.com/jcsvwinston/quark
	Name string `json:"name"` // p.ej. (*Query[T]).UpsertBatch o WithReplicas
	Kind string `json:"kind"` // func | method | type | var
}

Symbol es un identificador exportado de la superficie pública de Quark.

func (Symbol) Key

func (s Symbol) Key() string

Key es la clave canónica usada en cobertura y allowlist.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL