report

package
v0.511.0 Latest Latest
Warning

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

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

README

Domain Report Module

Audit result aggregation, summary counts, and verdict calculation.

Files

File Responsibility
result.go Defines result types and verdict aggregation
result_test.go Verifies verdict and summary behavior
action_summary.go Derives a human-oriented action summary from findings and catalog entries
action_summary_test.go Verifies action summary grouping, ordering, and fallbacks

Exports

  • Verdict
  • Explanation
  • ImpactSource
  • ImpactRisk
  • ImpactConfidence
  • Impact
  • StatementResult
  • Summary
  • Result
  • Aggregate()
  • ActionSummaryOptions
  • ActionSummary
  • ActionItem
  • BuildActionSummary()

Action Summary

BuildActionSummary is a derived human-report helper. It groups statement and global findings by rule_id and orders them by remediation priority so a human reader can decide what to fix first.

  • It is derived from report.Result and internal/domain/rule/catalog entries. It does not change Result JSON shape.
  • It uses rule.Level (blocker, warning, notice). It does not introduce a severity field.
  • It does not parse SQL, run the audit, evaluate rules, read raw SQL, or read metadata. It only reads existing findings and catalog metadata.
  • Statement indexes are 1-based positions into Result.Statements and are deduplicated within a rule group; global findings set HasGlobalFindings and carry no statement index.
  • Ordering is deterministic: level priority (blocker, warning, notice), then count descending, then rule_id ascending.
  • ActionSummaryOptions.Limit <= 0 means no truncation; a positive limit truncates Items but preserves TotalItems.
  • An empty result returns a non-nil empty Items slice.
  • It does not mutate Result or catalog entries.

Notes

  • StatementResult and Result now expose an optional Explanation field for additive, shared result context without changing verdict calculation.
  • StatementResult also exposes an optional Impact field for additive statement-level DML impact estimates without changing verdict aggregation semantics.
  • Result now also exposes an Unsupported array for structured partial-support outcomes, allowing supported statements to audit while recognized-but-unsupported statements are still returned to callers.
  • The additive Impact payload carries estimated_rows, estimated_ratio, risk_level, confidence, source, reason_codes, and optional notes for conservative UPDATE / DELETE estimation.

Dependencies

  • Upstream: application audit orchestration
  • Downstream: internal/domain/rule, internal/domain/rule/catalog (catalog read by BuildActionSummary)

Update Rule

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

Documentation

Overview

Package report defines audit results, summaries, and verdict aggregation. This file adds a derived action summary that groups findings by rule for human reports. input: report.Result findings and rule catalog entries output: derived action summary items ordered by remediation priority pos: derived human-report helper; does not change Result JSON and does not run the audit note: if this file changes, update this header and module README.md.

Package report defines audit results, summaries, and verdict aggregation. input: statement findings and global findings from audit evaluation output: normalized audit results for CLI, APIs, and future integrations pos: domain reporting model and verdict aggregation logic note: if this file changes, update this header and module README.md.

Index

Constants

View Source 
const (
	ImpactSourceShape    = spec.ImpactSourceShape
	ImpactSourceMetadata = spec.ImpactSourceMetadata
	ImpactSourcePlan     = spec.ImpactSourcePlan

	ImpactRiskLow     = spec.ImpactRiskLow
	ImpactRiskMedium  = spec.ImpactRiskMedium
	ImpactRiskHigh    = spec.ImpactRiskHigh
	ImpactRiskUnknown = spec.ImpactRiskUnknown

	ImpactConfidenceLow    = spec.ImpactConfidenceLow
	ImpactConfidenceMedium = spec.ImpactConfidenceMedium
	ImpactConfidenceHigh   = spec.ImpactConfidenceHigh
)

Variables

This section is empty.

Functions

This section is empty.

Types

type ActionItem added in v0.300.0 

type ActionItem struct {
	RuleID            string
	Level             rule.Level
	Count             int
	Summary           string
	Suggestion        string
	StatementIndexes  []int
	HasGlobalFindings bool
	ExplainCommand    string
}

ActionItem describes one rule group in the action summary. It carries rule-level priority and counts only; it does not hold raw SQL or finding metadata, so it is safe to render in human reports.

type ActionSummary added in v0.300.0 

type ActionSummary struct {
	Items      []ActionItem
	TotalItems int
}

ActionSummary is the derived, human-oriented grouping of audit findings by rule. It is derived from report.Result and does not change the Result JSON shape. It uses rule.Level (blocker, warning, notice) and never introduces a severity field.

func BuildActionSummary added in v0.300.0 

func BuildActionSummary(result Result, entries []catalog.Entry, options ActionSummaryOptions) ActionSummary

BuildActionSummary derives an action summary from a report result and rule catalog entries.

It groups statement findings and global findings by rule ID, derives each group's highest-priority level and total count, prefers catalog summary/suggestion text and falls back to finding text when a rule is absent from the catalog, and orders groups by remediation priority (blocker, warning, notice; then count descending; then rule ID ascending).

BuildActionSummary is a pure derivation: it does not parse SQL, run the audit, inspect raw SQL, or mutate result or entries. Statement indexes are 1-based positions into result.Statements and are deduplicated within a group. An empty result returns a non-nil Items slice and TotalItems 0.

type ActionSummaryOptions added in v0.300.0 

type ActionSummaryOptions struct {
	Limit int
}

ActionSummaryOptions controls action summary derivation. A Limit of zero or less means the core performs no truncation.

type Explanation added in v0.6.2 

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

Explanation captures additive human- and machine-readable context for a result.

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 captures the additive statement-level DML impact estimate exposed on results.

type ImpactConfidence added in v0.14.0 

type ImpactConfidence = spec.ImpactConfidence

ImpactConfidence mirrors the shared DML impact confidence contract on report outputs.

type ImpactRisk added in v0.14.0 

type ImpactRisk = spec.ImpactRisk

ImpactRisk mirrors the shared DML impact risk contract on report outputs.

type ImpactSource added in v0.14.0 

type ImpactSource = spec.ImpactSource

ImpactSource mirrors the shared DML impact source contract on report outputs.

type Result 

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

Result is the aggregated audit output.

func Aggregate 

func Aggregate(statements []StatementResult, findings []rule.Finding) Result

Aggregate builds a final Result from statement and global findings.

type RuleSummary added in v0.19.0 

type RuleSummary struct {
	Loaded     int                `json:"loaded"`
	Applicable int                `json:"applicable"`
	Skipped    []rule.SkippedRule `json:"skipped,omitempty"`
}

RuleSummary captures rule applicability statistics across the full audit.

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      []rule.Finding `json:"findings,omitempty"`
	Impact        *Impact        `json:"impact,omitempty"`
	Explanation   *Explanation   `json:"explanation,omitempty"`
}

StatementResult stores 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 counts for the full audit result.

type Verdict 

type Verdict string

Verdict describes the final 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.