deltascope

package
v0.15.0 Latest Latest
Warning

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

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

README

Public Package Module

Stable public package surface for library consumers.

Files

File Responsibility
doc.go Declares the public package placeholder
audit.go Exposes the stable public audit API, optional metadata-provider hooks, and public result/request types
version.go Publishes the default semantic version and canonical ASCII logo
audit_test.go Verifies the public audit API with defaults, overrides, multi-statement input, PostgreSQL request routing, and metadata-aware request plumbing

Exports

  • Audit(ctx, request)
  • Request
  • MetadataProvider
  • Metadata
  • InstanceFacts
  • TableSnapshot
  • Table
  • Column
  • Index
  • Constraint
  • Result
  • StatementResult
  • Explanation
  • Finding
  • FindingExplanation
  • ExplanationMetadata
  • Level Public finding severity type for blocker, warning, and notice
  • Summary
  • Location
  • Dialect Includes DialectPostgreSQL for PostgreSQL request routing support
  • Verdict
  • DefaultVersion
  • Logo

Notes

  • Request now carries top-level Schema and MetadataProvider fields so CLI, HTTP, and library consumers can opt into metadata-aware audits without changing the offline call shape.
  • Result and StatementResult expose an optional Explanation field for additive shared result context without changing verdict semantics. The built-in audit flow populates these aggregate fields whenever findings are present.
  • Result now also exposes an Unsupported array so library consumers can inspect structured partial-support PostgreSQL outcomes.
  • ErrUnsupportedStatement is returned when unsupported statements are present, while still returning a populated Result for supported statements.
  • Finding now exposes an optional Explanation field so library consumers can read structured per-finding why, risk, suggestion, and metadata-status notes directly.
  • DefaultVersion is now v0.15.0, which matches the source-build baseline used by the CLI, HTTP server, official MCP server release artifacts, and the dedicated PostgreSQL CLI release path.
  • The public package surface stays stable in v0.15.0; this release adds PostgreSQL request routing and release-surface alignment while keeping the exported pkg/deltascope contract additive.

Dependencies

  • Upstream: external library consumers
  • Downstream: context, internal/application/audit, internal/domain/report, internal/domain/rule, internal/domain/spec

Update Rule

  • If members/interfaces/dependencies change, update this file in same change.

Documentation

Overview

Package deltascope exposes the public library surface for consumers. input: public audit requests carrying SQL text, dialect, optional config path, and optional metadata providers output: stable audit results for embedding DeltaScope in tools and agents pos: public audit API above the internal application service note: if this file changes, update this header and module README.md.

Package deltascope exposes the public library surface for consumers. input: external library calls into the DeltaScope audit engine output: stable exported API for embedding DeltaScope pos: public package boundary above internal application services note: if this file changes, update this header and module README.md.

Package deltascope exposes the stable public audit API. input: build metadata consumers and public version/logo queries output: shared default version and ASCII logo values for CLIs and services pos: public package metadata alongside the stable audit entrypoint note: if this file changes, update this header and module README.md.

Index

Constants

View Source 
const (
	ImpactSourceShape    ImpactSource = "shape"
	ImpactSourceMetadata ImpactSource = "metadata"
	ImpactSourcePlan     ImpactSource = "plan"

	ImpactRiskLow     ImpactRisk = "low"
	ImpactRiskMedium  ImpactRisk = "medium"
	ImpactRiskHigh    ImpactRisk = "high"
	ImpactRiskUnknown ImpactRisk = "unknown"

	ImpactConfidenceLow    ImpactConfidence = "low"
	ImpactConfidenceMedium ImpactConfidence = "medium"
	ImpactConfidenceHigh   ImpactConfidence = "high"
)
View Source 
const (
	// DefaultVersion is the repository's current default semantic version.
	DefaultVersion = "v0.15.0"

	Logo = "    ____       ____        _____                     \n" +
		"   / __ \\___  / / /_____ _/ ___/_________  ____  ___ \n" +
		"  / / / / _ \\/ / __/ __ `/\\__ \\/ ___/ __ \\/ __ \\/ _ \\\n" +
		" / /_/ /  __/ / /_/ /_/ /___/ / /__/ /_/ / /_/ /  __/\n" +
		"/_____/\\___/_/\\__/\\__,_//____/\\___/\\____/ .___/\\___/ \n" +
		"                                       /_/           "
)

Variables

View Source 
var ErrUnsupportedStatement = errors.New("deltascope audit includes unsupported statements")

Functions

This section is empty.

Types

type Column 

type Column = spec.Column

Column mirrors the domain column shape used inside metadata snapshots.

type Constraint 

type Constraint = spec.Constraint

Constraint mirrors the domain constraint shape used inside metadata snapshots.

type Dialect 

type Dialect string

Dialect identifies the SQL dialect for public callers. 

const (
	DialectMySQL      Dialect = "mysql"
	DialectTiDB       Dialect = "tidb"
	DialectPostgreSQL Dialect = "postgresql"
)

type Explanation added in v0.6.2 

type Explanation struct {
	Summary string   `json:"summary,omitempty"`
	Reasons []string `json:"reasons,omitempty"`
}

Explanation is the stable public result-level explanation shape.

type ExplanationMetadata added in v0.6.2 

type ExplanationMetadata struct {
	Status string `json:"status,omitempty"`
	Note   string `json:"note,omitempty"`
}

ExplanationMetadata describes how metadata availability affected a public finding explanation.

type Finding 

type Finding struct {
	RuleID         string              `json:"rule_id"`
	Level          Level               `json:"level"`
	Message        string              `json:"message"`
	StatementIndex int                 `json:"statement_index,omitempty"`
	StatementKind  string              `json:"statement_kind,omitempty"`
	Location       *Location           `json:"location,omitempty"`
	Suggestion     string              `json:"suggestion,omitempty"`
	Metadata       map[string]any      `json:"metadata,omitempty"`
	Explanation    *FindingExplanation `json:"explanation,omitempty"`
}

Finding is the stable public finding shape.

type FindingExplanation added in v0.6.2 

type FindingExplanation struct {
	Summary    string               `json:"summary,omitempty"`
	Why        string               `json:"why,omitempty"`
	Risk       string               `json:"risk,omitempty"`
	Suggestion string               `json:"suggestion,omitempty"`
	Metadata   *ExplanationMetadata `json:"metadata,omitempty"`
}

FindingExplanation is the stable public per-finding explanation shape.

type Impact added in v0.14.0 

type Impact struct {
	EstimatedRows  *int64           `json:"estimated_rows,omitempty"`
	EstimatedRatio *float64         `json:"estimated_ratio,omitempty"`
	RiskLevel      ImpactRisk       `json:"risk_level,omitempty"`
	Confidence     ImpactConfidence `json:"confidence,omitempty"`
	Source         ImpactSource     `json:"source,omitempty"`
	ReasonCodes    []string         `json:"reason_codes,omitempty"`
	Notes          []string         `json:"notes,omitempty"`
}

Impact is the stable public statement-level DML impact estimate shape.

type ImpactConfidence added in v0.14.0 

type ImpactConfidence string

ImpactConfidence identifies the public estimate-confidence bucket.

type ImpactRisk added in v0.14.0 

type ImpactRisk string

ImpactRisk identifies the public conservative risk bucket for a DML statement.

type ImpactSource added in v0.14.0 

type ImpactSource string

ImpactSource identifies the public origin of a statement-level DML impact estimate.

type Index 

type Index = spec.Index

Index mirrors the domain index shape used inside metadata snapshots.

type InstanceFacts 

type InstanceFacts = spec.InstanceFacts

InstanceFacts mirror metadata-aware instance facts for public providers.

type Level 

type Level string

Level identifies the public finding severity. 

const (
	LevelBlocker Level = "blocker"
	LevelWarning Level = "warning"
	LevelNotice  Level = "notice"
)

type Location 

type Location struct {
	Line   int `json:"line,omitempty"`
	Column int `json:"column,omitempty"`
}

Location identifies a public source span when available.

type Metadata 

type Metadata = spec.Metadata

Metadata mirrors the optional domain metadata facts exposed on statements.

type MetadataProvider 

type MetadataProvider interface {
	LoadInstanceFacts(ctx context.Context, dialect Dialect, schema string) (*InstanceFacts, error)
	LoadTableSnapshot(ctx context.Context, dialect Dialect, schema string, table string) (*TableSnapshot, error)
}

MetadataProvider supplies optional metadata-aware facts for one public audit request.

type Request 

type Request struct {
	SQL              string
	Dialect          Dialect
	ConfigPath       string
	Schema           string
	MetadataProvider MetadataProvider
}

Request describes one public audit invocation.

type Result 

type Result struct {
	Verdict        Verdict                  `json:"verdict"`
	Summary        Summary                  `json:"summary"`
	Statements     []StatementResult        `json:"statements,omitempty"`
	GlobalFindings []Finding                `json:"global_findings,omitempty"`
	Unsupported    []spec.UnsupportedDetail `json:"unsupported,omitempty"`
	Explanation    *Explanation             `json:"explanation,omitempty"`
}

Result is the stable public audit output.

func Audit 

func Audit(ctx context.Context, request Request) (Result, error)

Audit executes the stable public audit flow.

type StatementResult 

type StatementResult struct {
	Index         int          `json:"index"`
	Kind          string       `json:"kind"`
	RawSQL        string       `json:"raw_sql,omitempty"`
	NormalizedSQL string       `json:"normalized_sql,omitempty"`
	Findings      []Finding    `json:"findings,omitempty"`
	Impact        *Impact      `json:"impact,omitempty"`
	Explanation   *Explanation `json:"explanation,omitempty"`
}

StatementResult stores public findings for a single SQL statement.

type Summary 

type Summary struct {
	Statements int `json:"statements"`
	Blockers   int `json:"blockers"`
	Warnings   int `json:"warnings"`
	Notices    int `json:"notices"`
}

Summary captures high-level public audit counts.

type Table 

type Table = spec.Table

Table mirrors the domain table shape used inside metadata snapshots.

type TableSnapshot 

type TableSnapshot = spec.TableSnapshot

TableSnapshot mirrors metadata-aware target table snapshots for public providers.

type Verdict 

type Verdict string

Verdict identifies the final public audit outcome. 

const (
	VerdictPass   Verdict = "pass"
	VerdictReview Verdict = "review"
	VerdictReject Verdict = "reject"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.