audit

Documentation

Index

• Constants
• func IgnoreCoverage(impact ContextImpact) string
• type AuditReport
  • func NewReport(projectPath string) AuditReport
  • func (r AuditReport) WithSummary() AuditReport
• type AuditRequest
• type AuditSummary
• type Auditor
  • func NewAuditor() Auditor
  • func (a Auditor) AuditProject(ctx context.Context, req AuditRequest) (AuditReport, error)
  • func (Auditor) DetectProject(ctx context.Context, projectPath string) (ProjectDetection, error)
  • func (a Auditor) SuggestLoadouts(ctx context.Context, req SuggestRequest) ([]LoadoutSuggestion, error)
• type ContextImpact
  • func AggregateContextImpact(findings []Finding) ContextImpact
  • func ContentImpact(content []byte, kind adapters.TargetKind) ContextImpact
  • func IgnoreContextImpact(count int) ContextImpact
  • func MCPContextImpact(count int) ContextImpact
  • func SkillContextImpact(count int) ContextImpact
• type Finding
• type FindingCategory
• type FindingEvidence
• type LoadoutSuggestion
• type ProjectDetection
• type ProjectIndicator
• type RiskLevel
• type SuggestRequest

Constants

const (
	LoadoutWebAppBuilder    = "web-app-builder"
	LoadoutWordPressBuilder = "wordpress-builder"
	LoadoutBrowserQA        = "browser-qa"
)

const (
	APIVersion = "contextcart.dev/v1"
	KindReport = "AuditReport"
)

Functions

func IgnoreCoverage

func IgnoreCoverage(impact ContextImpact) string

IgnoreCoverage summarizes whether the audit found traversal-hygiene coverage.

Types

type AuditReport

type AuditReport struct {
	APIVersion  string            `json:"apiVersion"`
	Kind        string            `json:"kind"`
	ProjectPath string            `json:"projectPath"`
	GeneratedAt time.Time         `json:"generatedAt"`
	Scopes      []string          `json:"scopes,omitempty"`
	Summary     AuditSummary      `json:"summary"`
	Findings    []Finding         `json:"findings,omitempty"`
	Metadata    map[string]string `json:"metadata,omitempty"`
}

AuditReport is the read-only project audit result.

func NewReport

func NewReport(projectPath string) AuditReport

NewReport returns an initialized audit report for callers that add findings incrementally.

func (AuditReport) WithSummary

func (r AuditReport) WithSummary() AuditReport

WithSummary recomputes summary counters from the report's findings.

type AuditRequest

type AuditRequest struct {
	ProjectPath string           `json:"projectPath,omitempty"`
	Home        string           `json:"home,omitempty"`
	Adapters    []string         `json:"adapters,omitempty"`
	Scopes      []adapters.Scope `json:"scopes,omitempty"`
}

AuditRequest selects the project and scopes to inspect. Project scope is the default. User/global scopes are read-only and opt-in.

type AuditSummary

type AuditSummary struct {
	Findings       int           `json:"findings"`
	HighRisk       int           `json:"highRisk,omitempty"`
	MediumRisk     int           `json:"mediumRisk,omitempty"`
	LowRisk        int           `json:"lowRisk,omitempty"`
	HighContext    int           `json:"highContext,omitempty"`
	MediumContext  int           `json:"mediumContext,omitempty"`
	LowContext     int           `json:"lowContext,omitempty"`
	ContextImpact  ContextImpact `json:"contextImpact"`
	MCPServers     int           `json:"mcpServers,omitempty"`
	Skills         int           `json:"skills,omitempty"`
	IgnoreCoverage string        `json:"ignoreCoverage,omitempty"`
}

AuditSummary contains stable counters for human and machine output.

type Auditor

type Auditor struct{}

Auditor scans known adapter targets without writing files.

func NewAuditor

func NewAuditor() Auditor

NewAuditor creates a read-only audit service.

func (Auditor) AuditProject

func (a Auditor) AuditProject(ctx context.Context, req AuditRequest) (AuditReport, error)

AuditProject scans project and optionally user/global adapter targets. It reports malformed files as findings and keeps scanning other targets.

func (Auditor) DetectProject

func (Auditor) DetectProject(ctx context.Context, projectPath string) (ProjectDetection, error)

DetectProject inspects static project files for known ecosystem indicators.

func (Auditor) SuggestLoadouts

func (a Auditor) SuggestLoadouts(ctx context.Context, req SuggestRequest) ([]LoadoutSuggestion, error)

SuggestLoadouts returns ranked loadout recommendations from static project indicators without writing files or reading generated directories.

type ContextImpact

type ContextImpact struct {
	Level      RiskLevel `json:"level"`
	Lines      int       `json:"lines,omitempty"`
	Bytes      int       `json:"bytes,omitempty"`
	MCPServers int       `json:"mcpServers,omitempty"`
	Skills     int       `json:"skills,omitempty"`
	Ignores    int       `json:"ignores,omitempty"`
	Reason     string    `json:"reason,omitempty"`
}

ContextImpact reports static context-cost indicators for a report or finding.

func AggregateContextImpact

func AggregateContextImpact(findings []Finding) ContextImpact

AggregateContextImpact folds finding-level context costs into report summary counters without inspecting file contents again.

func ContentImpact

func ContentImpact(content []byte, kind adapters.TargetKind) ContextImpact

ContentImpact computes static context cost for one file target.

func IgnoreContextImpact

func IgnoreContextImpact(count int) ContextImpact

IgnoreContextImpact records traversal-hygiene coverage from active ignores.

func MCPContextImpact

func MCPContextImpact(count int) ContextImpact

MCPContextImpact computes context impact from active MCP server count.

func SkillContextImpact

func SkillContextImpact(count int) ContextImpact

SkillContextImpact computes context impact from active skill count.

type Finding

type Finding struct {
	ID              string            `json:"id,omitempty"`
	Code            string            `json:"code"`
	Category        FindingCategory   `json:"category"`
	Title           string            `json:"title,omitempty"`
	Message         string            `json:"message"`
	AdapterID       string            `json:"adapterId,omitempty"`
	Scope           string            `json:"scope,omitempty"`
	Path            string            `json:"path,omitempty"`
	ConfigKey       string            `json:"configKey,omitempty"`
	NormalizedValue string            `json:"normalizedValue,omitempty"`
	ComponentRef    components.Ref    `json:"componentRef,omitempty"`
	ContextImpact   ContextImpact     `json:"contextImpact,omitempty"`
	Risk            RiskLevel         `json:"risk"`
	RiskReasons     []string          `json:"riskReasons,omitempty"`
	Evidence        []FindingEvidence `json:"evidence,omitempty"`
	Metadata        map[string]string `json:"metadata,omitempty"`
}

Finding is one actionable or informational audit result.

type FindingCategory

type FindingCategory string

FindingCategory names the broad source of an audit finding.

const (
	FindingInstructions FindingCategory = "instructions"
	FindingSkill        FindingCategory = "skill"
	FindingMCP          FindingCategory = "mcp"
	FindingIgnore       FindingCategory = "ignore"
	FindingPermission   FindingCategory = "permission"
	FindingMalformed    FindingCategory = "malformed"
	FindingUnmanaged    FindingCategory = "unmanaged"
	FindingSecret       FindingCategory = "secret"
	FindingHook         FindingCategory = "hook"
	FindingSuggestion   FindingCategory = "suggestion"
)

type FindingEvidence

type FindingEvidence struct {
	Path     string            `json:"path,omitempty"`
	Line     int               `json:"line,omitempty"`
	Key      string            `json:"key,omitempty"`
	Value    string            `json:"value,omitempty"`
	Reason   string            `json:"reason,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

FindingEvidence stores non-sensitive evidence used to produce a finding.

type LoadoutSuggestion

type LoadoutSuggestion struct {
	LoadoutID  string             `json:"loadoutId"`
	Confidence int                `json:"confidence"`
	Reasons    []string           `json:"reasons,omitempty"`
	Evidence   []ProjectIndicator `json:"evidence,omitempty"`
}

LoadoutSuggestion ranks a starter kit recommendation with evidence.

type ProjectDetection

type ProjectDetection struct {
	ProjectPath string              `json:"projectPath"`
	Indicators  []ProjectIndicator  `json:"indicators,omitempty"`
	Suggestions []LoadoutSuggestion `json:"suggestions,omitempty"`
}

ProjectDetection is the static project fingerprint used for suggestions.

type ProjectIndicator

type ProjectIndicator struct {
	Kind     string `json:"kind"`
	Path     string `json:"path"`
	Value    string `json:"value,omitempty"`
	Evidence string `json:"evidence,omitempty"`
}

ProjectIndicator is one static file or dependency signal found in a project.

type RiskLevel

type RiskLevel string

RiskLevel is the stable low/medium/high scale used by audit JSON and tables.

const (
	RiskLow    RiskLevel = "low"
	RiskMedium RiskLevel = "medium"
	RiskHigh   RiskLevel = "high"
)

type SuggestRequest

type SuggestRequest struct {
	ProjectPath string `json:"projectPath,omitempty"`
}

SuggestRequest selects a project for read-only loadout suggestions.