audit

package
v0.410.0 Latest Latest
Warning

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

 Go to latest Published: Jul 19, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

README

Application Audit Module

Application orchestration for parsing and, later, evaluating SQL audit requests.

Files

File Responsibility
parse.go Dispatches by dialect, builds application-owned parsed statements from infrastructure-backed parser adapters via parser-neutral extractors, and leaves PostgreSQL build-tagged support behind the Phase 3 adapter seam
parse_pg.go Implements PostgreSQL parsing when built with the postgresql tag
parse_pg_stub.go Returns the PG-capable build guidance error when PostgreSQL support is not compiled in
parse_test.go Verifies that application parsing hides parser-specific AST details
extract.go Converts parsed statements into first-pass domain Statement values by invoking parser-neutral extractors and attaching shape-only DML impact facts
extract_test.go Verifies representative DDL and DML extraction behavior, including create-like/create-as/partition flags plus enriched create-table facts, preserved backticked-keyword and unnamed-index names, extracted column charset/collation facts, normalized row-format and auto-increment-init options, explicit DDL lifecycle operations, richer alter-table detail including explicit statement-local change facts, multi-column add expansion, non-index constraint handling, and extracted DML target-table plus predicate-shape facts
impact.go Maps extracted DML predicate shapes to conservative offline impact estimates, populates statement impact objects with estimated_rows, estimated_ratio, risk_level, confidence, source, reason_codes, and optional notes, upgrades shape-derived sources to metadata after enrichment, and refines the narrow primary-key-on-id case when metadata snapshots confirm PRIMARY(id) plus optional table_rows facts
impact_test.go Verifies shape-only impact estimation plus post-enrichment metadata source upgrades, unique-equality refinement, and offline preservation behavior for representative UPDATE and DELETE shapes and their additive impact payloads
evaluate.go Applies registered rules, enriches findings with explanation metadata, and aggregates statement/global findings into report output while preserving statement-level DML impact estimates
evaluate_test.go Verifies application-owned report-flow integration and explanation enrichment over the rule registry
explain.go Joins evaluated findings with shipped catalog metadata and statement metadata availability notes
service.go Orchestrates the full audit flow across policy loading, parsing, extraction, top-level request metadata plumbing, optional metadata enrichment, post-enrichment DML impact attachment/refinement, rule registration, evaluation, partial-support error propagation for unsupported statements, and diagnostic evidence attachment for parser-error and unsupported outcomes
service_test.go Verifies the end-to-end application audit use case with defaults, config overrides, multi-statement SQL, PostgreSQL validation-boundary acceptance, mixed supported/unsupported partial results, metadata enrichment behavior, metadata-backed DML impact surfacing, and schema-only context/top-level request plumbing
metadata.go Defines the optional metadata-provider, index-owner resolver, plan estimator, and object-resolver seams, then attaches schema, instance, target-table, and non-table object snapshots to statements before evaluation
diagnostics.go Defines diagnostic evidence constants (classification, reason, action_hint, guidance codes, evidence refs) and helpers for constructing parser-error and unsupported statement diagnostics with optional guidance classification
ddl_coverage_catalog_query.go Defines CatalogEntry, CatalogQuery, CatalogResult, LoadCatalog, QueryCatalog, and Validate for reading and filtering the checked-in DDL coverage catalog without invoking the audit engine

Exports

  • Parse(sql string, dialect spec.Dialect)
  • Extract(parsed ParsedSQL)
  • EvaluateStatements(registry, statements)
  • AuditSQL(ctx, request)
  • Request
  • MetadataRequest
  • MetadataProvider
  • IndexOwnerResolver
  • PlanEstimator
  • ObjectResolver
  • Service
  • NewService()
  • Service.Audit(ctx, request)
  • ParsedStatement
  • ParsedSQL
  • PostgreSQLCapabilityBoundaryError
  • CatalogEntry
  • CatalogQuery
  • CatalogResult
  • LoadCatalog(path string) ([]CatalogEntry, error)
  • QueryCatalog(entries []CatalogEntry, q CatalogQuery) CatalogResult
  • CatalogQuery.Validate() error

Notes

  • report.Result carries an additive Diagnostics []spec.Diagnostic field. When the parser fails to parse a statement (parser-error path) or when a statement is an explicitly unsupported boundary (unsupported path), diagnostics are populated with classification (parser_error or unsupported_statement), reason, action_hint, audited (always false), and dialect. Parser-error diagnostics may also carry guidance_code (e.g., parser_upgrade_candidate) and evidence_ref (GitHub documentation URL) when the statement form matches a known unsupported boundary. Diagnostics do not contain raw SQL text, parser near ... fragments, or any other forbidden payload.

Dependencies

  • Upstream: future CLI and public audit entrypoints
  • Downstream: context, fmt, internal/application/policy, internal/domain/report, internal/domain/rule, internal/domain/rule/ddl, internal/domain/rule/dml, internal/domain/spec, internal/infrastructure/parser/postgresql, internal/infrastructure/parser/tidb

Update Rule

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

Documentation

Overview

Package audit orchestrates audit use cases at the application layer. input: extracted domain statements and the registered rule engine output: aggregated report results with statement/global findings and preserved statement-level impact estimates pos: application evaluation step between extraction/metadata refinement and reporting note: if this file changes, update this header and module README.md.

Package audit enriches evaluated findings with shared explanation metadata. input: rule findings, shipped catalog entries, and optional statement metadata context output: additive per-finding explanation data without changing verdict semantics pos: application explanation enrichment between evaluation and report aggregation note: if this file changes, update this header and module README.md.

Package audit orchestrates audit use cases at the application layer. input: application-owned parsed SQL statements and parser-neutral extractors output: first-pass StatementSpec values plus attached shape-only impact facts for later rule evaluation pos: application extraction step between parsing and rule execution note: if this file changes, update this header and module README.md.

Package audit orchestrates audit use cases at the application layer. input: extracted statement-local DML shape facts plus optional metadata snapshots for refinement output: conservative DML impact estimates attached during extraction and upgraded after metadata enrichment pos: application impact estimation step between extraction, metadata enrichment, and rule evaluation note: if this file changes, update this header and module README.md.

Package audit orchestrates audit use cases at the application layer. input: optional metadata providers plus parsed statement targets for enrichment output: metadata-enriched statements for rules that can use live instance or schema facts pos: application-layer bridge between provider-backed metadata and domain statements note: if this file changes, update this header and module README.md.

Package audit provides application-layer parser mismatch hints.

Package audit orchestrates audit use cases at the application layer. input: SQL text, selected dialect, and infrastructure-backed parser adapters output: application-owned parsed statements for later extraction and rule evaluation pos: application parsing entrypoint between interfaces and parser infrastructure note: if this file changes, update this header and module README.md.

Package audit orchestrates audit use cases at the application layer. input: audit requests carrying SQL text, dialect, optional policy override paths, and optional metadata providers output: end-to-end audit results assembled from policy loading, parsing, extraction, metadata enrichment, post-enrichment impact refinement, and rule evaluation pos: application service entrypoint for the unified offline/metadata-aware SQL audit use case with preserved statement impact estimates note: if this file changes, update this header and module README.md.

Index

Constants

View Source 
const (
	// DiagnosticParserError classifies parser-error outcomes.
	DiagnosticParserError = "parser_error"
	// DiagnosticUnsupportedStatement classifies structured unsupported outcomes.
	DiagnosticUnsupportedStatement = "unsupported_statement"

	// ParserErrorActionHint is the generic safe next step for parser-error diagnostics.
	ParserErrorActionHint = "" /* 138-byte string literal not displayed */
	// UnsupportedActionHint is the generic safe next step for unsupported-statement diagnostics.
	UnsupportedActionHint = "" /* 131-byte string literal not displayed */

	// DiagnosticGuidanceParserUpgradeCandidate identifies parser-error cases that would become
	// parseable after an upstream parser/library upgrade.
	DiagnosticGuidanceParserUpgradeCandidate = "parser_upgrade_candidate"

	// ParserUpgradeCandidateEvidenceRef is the stable GitHub documentation URL for parser-upgrade
	// candidate evidence.
	ParserUpgradeCandidateEvidenceRef = "https://github.com/Fanduzi/DeltaScope/blob/main/docs/reference/cli.md#parser-upgrade-candidate-evidence-v02500"
)

Variables

View Source 
var (
	// ErrEmptySQL indicates the request did not include auditable SQL text.
	ErrEmptySQL = errors.New("audit SQL must not be empty")
	// ErrUnknownDialect indicates the request did not specify a supported dialect.
	ErrUnknownDialect = errors.New("audit dialect must be mysql, tidb, or postgresql")
	// ErrUnsupportedStatement indicates at least one parsed statement is recognized but unsupported.
	ErrUnsupportedStatement = errors.New("audit includes unsupported statements")
)

Functions

func AuditSQL 

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

AuditSQL is the convenience application entrypoint used by outer adapters.

func EvaluateStatements 

func EvaluateStatements(ctx context.Context, registry *rule.Registry, statements []spec.Statement) (report.Result, error)

EvaluateStatements applies registered rules and aggregates their findings into a report result.

func Extract 

func Extract(ctx context.Context, parsed ParsedSQL) ([]spec.Statement, error)

Extract converts parsed statements into first-pass domain StatementSpec values.

Types

type CatalogEntry added in v0.280.0 

type CatalogEntry struct {
	Dialect        string   `json:"dialect"`
	Family         string   `json:"family"`
	Form           string   `json:"form"`
	Classification string   `json:"classification"`
	FindingRuleIDs []string `json:"finding_rule_ids"`
	GuidanceCode   string   `json:"guidance_code,omitempty"`
	EvidenceRef    string   `json:"evidence_ref,omitempty"`
	Notes          string   `json:"notes"`
}

CatalogEntry represents a single DDL coverage catalog entry returned by QueryCatalog. Fields mirror the v0.270.0 catalog JSON schema.

func LoadCatalog added in v0.280.0 

func LoadCatalog(path string) ([]CatalogEntry, error)

LoadCatalog reads the DDL coverage catalog from the given file path and returns entries in their canonical (deterministic) order.

type CatalogQuery added in v0.280.0 

type CatalogQuery struct {
	Dialect        string
	Classification string
	GuidanceCode   string
	Family         string
	Form           string
	Search         string
	Limit          int
}

CatalogQuery holds filter parameters for querying the DDL coverage catalog. All string fields are optional; zero values mean "no filter".

func (CatalogQuery) Validate added in v0.280.0 

func (q CatalogQuery) Validate() error

Validate checks that enum filter values are recognized. Returns an error describing the first invalid field, or nil.

type CatalogResult added in v0.280.0 

type CatalogResult struct {
	Entries []CatalogEntry `json:"entries"`
	Total   int            `json:"total"`
}

CatalogResult holds the query output: a filtered slice of entries plus summary metadata.

func QueryCatalog added in v0.280.0 

func QueryCatalog(entries []CatalogEntry, q CatalogQuery) CatalogResult

QueryCatalog filters entries according to the query parameters. It returns a CatalogResult with the matching entries preserving their original deterministic order, and a total count. Empty results are a success, not an error.

type IndexOwnerResolver added in v0.18.0 

type IndexOwnerResolver interface {
	ResolveTableForIndex(ctx context.Context, dialect spec.Dialect, schema string, index string) (string, error)
}

IndexOwnerResolver optionally resolves standalone index statements back to owning tables.

type MetadataProvider 

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

MetadataProvider supplies optional instance and schema facts for one audit run.

type MetadataRequest 

type MetadataRequest struct {
	Schema   string
	Provider MetadataProvider
}

MetadataRequest describes one optional metadata-aware audit invocation.

type ObjectResolver added in v0.90.0 

type ObjectResolver interface {
	ResolveObject(ctx context.Context, dialect spec.Dialect, request spec.ObjectLookupRequest) (*spec.ObjectSnapshot, error)
}

ObjectResolver optionally resolves non-table database objects from live metadata.

type ParsedSQL 

type ParsedSQL struct {
	Dialect    spec.Dialect      `json:"dialect"`
	Statements []ParsedStatement `json:"statements"`
	Warnings   []string          `json:"warnings,omitempty"`
}

ParsedSQL is the application-owned parsing result used by later extraction steps.

func Parse 

func Parse(ctx context.Context, sql string, dialect spec.Dialect) (ParsedSQL, error)

Parse delegates SQL parsing to the dialect-specific parser adapter.

type ParsedStatement 

type ParsedStatement struct {
	Kind      spec.Kind               `json:"kind"`
	RawSQL    string                  `json:"raw_sql"`
	Line      int                     `json:"line,omitempty"`
	Column    int                     `json:"col,omitempty"`
	Extractor spec.StatementExtractor `json:"-"`
}

ParsedStatement keeps application-facing statement metadata while hiding parser nodes.

type PlanEstimator added in v0.18.0 

type PlanEstimator interface {
	LoadPlanEstimate(ctx context.Context, statement spec.Statement) (*spec.ImpactEstimate, error)
}

PlanEstimator optionally loads planner-backed DML impact estimates.

type PostgreSQLCapabilityBoundaryError added in v0.20.0 

type PostgreSQLCapabilityBoundaryError struct {
	Message string
}

PostgreSQLCapabilityBoundaryError reports that PostgreSQL parsing needs a PostgreSQL-capable build.

func (*PostgreSQLCapabilityBoundaryError) Error added in v0.20.0 

func (e *PostgreSQLCapabilityBoundaryError) Error() string

type Request 

type Request struct {
	SQL              string
	Dialect          spec.Dialect
	ConfigPath       string
	Schema           string
	MetadataProvider MetadataProvider
	Metadata         *MetadataRequest
}

Request describes one application-level audit invocation.

type Service 

type Service struct{}

Service coordinates the full audit use case.

func NewService 

func NewService() Service

NewService returns a ready-to-use audit service.

func (Service) Audit 

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

Audit executes the full SQL audit flow.

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.