project

Documentation

Overview

Package project provides project-level linting for LeapSQL.

Unlike SQL-level linting which analyzes individual statements, project-level linting examines the entire DAG structure, naming conventions, and cross-model relationships to detect architectural issues.

Rule Categories

Rules are organized into categories:

• modeling (PM*): DAG structure rules like root models, fanout, dependencies
• structure (PS*): Naming conventions and directory organization
• lineage (PL*): Column-level lineage analysis like passthrough detection

Model Type Inference

Models are classified into semantic types (staging, intermediate, marts) using a hybrid approach:

1. Frontmatter override (meta.type field)
2. Path-based detection (/staging/, /intermediate/, /marts/)
3. Prefix-based detection (stg_, int_, fct_, dim_)

This allows flexibility for teams using either folder-based or prefix-based conventions.

Usage

Create a Context from your discovered models and run the analyzer:

ctx := project.NewContext(models, graph)
analyzer := project.NewAnalyzer(config)
diagnostics := analyzer.Analyze(ctx)

Index

• func Clear()
• func Count() int
• func InferAndSetTypes(models map[string]*ModelInfo)
• func InferModelType(model *ModelInfo) core.ModelType
• func Register(rule RuleDef)
• func WrapRuleDef(def RuleDef) lint.ProjectRule
• type Analyzer
  • func NewAnalyzer(config *AnalyzerConfig) *Analyzer
  • func (a *Analyzer) Analyze(ctx *Context) []Diagnostic
  • func (a *Analyzer) AnalyzeProject(ctx lint.ProjectContext) []lint.Diagnostic
  • func (a *Analyzer) Disable(ruleID string)
  • func (a *Analyzer) Enable(ruleID string)
  • func (a *Analyzer) Name() string
• type AnalyzerConfig
  • func NewAnalyzerConfig() *AnalyzerConfig
• type Check
• type Context
  • func NewContext(models map[string]*ModelInfo, parents, children map[string][]string, ...) *Context
  • func NewContextWithStore(models map[string]*ModelInfo, parents, children map[string][]string, ...) *Context
  • func (c *Context) GetChildren(modelPath string) []string
  • func (c *Context) GetConfig() lint.ProjectHealthConfig
  • func (c *Context) GetModel(path string) (*ModelInfo, bool)
  • func (c *Context) GetModels() map[string]lint.ModelInfo
  • func (c *Context) GetParents(modelPath string) []string
  • func (c *Context) IsModel(name string) bool
  • func (c *Context) Models() map[string]*ModelInfo
  • func (c *Context) Store() SnapshotStore
• type Diagnostic
• type ModelInfo
• type Registry
• type RuleDef
  • func GetAll() []RuleDef
  • func GetByGroup(group string) []RuleDef
  • func GetByID(id string) (RuleDef, bool)
• type SnapshotStore

Functions

func Clear

func Clear()

Clear removes all registered rules. Used for testing.

func Count

func Count() int

Count returns the number of registered rules.

func InferAndSetTypes

func InferAndSetTypes(models map[string]*ModelInfo)

InferAndSetTypes infers and sets the Type field for all models in the context.

func InferModelType

func InferModelType(model *ModelInfo) core.ModelType

InferModelType determines the model type using hybrid logic:

1. Check frontmatter `type:` override (highest priority)
2. Check if path contains model type directory
3. Check if name has model type prefix

func Register

func Register(rule RuleDef)

Register adds a rule to the global registry. Call this from init() functions in rule packages.

func WrapRuleDef

func WrapRuleDef(def RuleDef) lint.ProjectRule

WrapRuleDef wraps a project RuleDef to implement lint.ProjectRule.

Types

type Analyzer

type Analyzer struct {
	// contains filtered or unexported fields
}

Analyzer runs project-level lint rules against the project context.

func NewAnalyzer

func NewAnalyzer(config *AnalyzerConfig) *Analyzer

NewAnalyzer creates a new project analyzer with optional configuration.

func (*Analyzer) Analyze

func (a *Analyzer) Analyze(ctx *Context) []Diagnostic

Analyze runs all registered project rules against the context.

func (*Analyzer) AnalyzeProject

func (a *Analyzer) AnalyzeProject(ctx lint.ProjectContext) []lint.Diagnostic

AnalyzeProject implements lint.ProjectProvider.

func (*Analyzer) Disable

func (a *Analyzer) Disable(ruleID string)

Disable disables a rule by ID.

func (*Analyzer) Enable

func (a *Analyzer) Enable(ruleID string)

Enable enables a previously disabled rule.

func (*Analyzer) Name

func (a *Analyzer) Name() string

Name implements lint.Provider.

type AnalyzerConfig

type AnalyzerConfig struct {
	// DisabledRules contains rule IDs to skip
	DisabledRules map[string]bool

	// SeverityOverrides changes the default severity of rules
	SeverityOverrides map[string]core.Severity

	// ProjectHealth contains thresholds and settings
	ProjectHealth lint.ProjectHealthConfig
}

AnalyzerConfig holds configuration for the project analyzer.

func NewAnalyzerConfig

func NewAnalyzerConfig() *AnalyzerConfig

NewAnalyzerConfig creates a default configuration.

type Check

type Check func(ctx *Context) []Diagnostic

Check is the function signature for project-level rule checks.

type Context

type Context struct {
	// contains filtered or unexported fields
}

Context provides all data needed for project-level analysis. It implements lint.ProjectContext to bridge the gap between the engine's model data and the lint package's requirements.

func NewContext

func NewContext(models map[string]*ModelInfo, parents, children map[string][]string, config lint.ProjectHealthConfig) *Context

NewContext creates a new project context for analysis.

func NewContextWithStore

func NewContextWithStore(models map[string]*ModelInfo, parents, children map[string][]string, config lint.ProjectHealthConfig, store SnapshotStore) *Context

NewContextWithStore creates a new project context with access to snapshot storage. This enables schema drift detection (PL05).

func (*Context) GetChildren

func (c *Context) GetChildren(modelPath string) []string

GetChildren implements lint.ProjectContext.

func (*Context) GetConfig

func (c *Context) GetConfig() lint.ProjectHealthConfig

GetConfig implements lint.ProjectContext.

func (*Context) GetModel

func (c *Context) GetModel(path string) (*ModelInfo, bool)

GetModel returns a specific model by path.

func (*Context) GetModels

func (c *Context) GetModels() map[string]lint.ModelInfo

GetModels implements lint.ProjectContext.

func (*Context) GetParents

func (c *Context) GetParents(modelPath string) []string

GetParents implements lint.ProjectContext.

func (*Context) IsModel

func (c *Context) IsModel(name string) bool

IsModel checks if a given table name is a known model.

func (*Context) Models

func (c *Context) Models() map[string]*ModelInfo

Models returns the internal model map for direct access.

func (*Context) Store

func (c *Context) Store() SnapshotStore

Store returns the snapshot store, if available. This is used by PL05 for schema drift detection.

type Diagnostic

type Diagnostic struct {
	RuleID   string
	Severity core.Severity
	Message  string
	Model    string // Model path that triggered this diagnostic
	FilePath string // File path for LSP integration

	// Remediation metadata
	DocumentationURL string // URL to rule documentation
	ImpactScore      int    // 0-100, used for health score weighting
	AutoFixable      bool   // true if fixes can be auto-applied
}

Diagnostic represents a project-level lint finding.

type ModelInfo

type ModelInfo struct {
	Path           string            // e.g., "staging.customers"
	Name           string            // e.g., "stg_customers"
	FilePath       string            // Absolute path to .sql file
	Type           core.ModelType    // Inferred or explicit model type
	Sources        []string          // Table references (deps)
	Columns        []core.ColumnInfo // Column-level lineage
	Materialized   string            // table, view, incremental
	Tags           []string
	Meta           map[string]any
	UsesSelectStar bool // true if model uses SELECT * or t.*
}

ModelInfo holds all metadata about a model for project-level analysis. This is a richer representation than lint.ModelInfo, with computed fields.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry stores registered project lint rules for discovery.

type RuleDef

type RuleDef struct {
	ID          string        // Unique identifier, e.g., "PM01"
	Name        string        // Human-readable name, e.g., "root-models"
	Group       string        // Category: "modeling", "structure", "lineage"
	Description string        // Human-readable description
	Severity    core.Severity // Default severity (uses unified core.Severity)
	Check       Check         // The check function
	ConfigKeys  []string      // Configuration keys this rule accepts

	// Documentation fields for richer rule documentation
	Rationale   string // Why this rule exists, what problems it prevents
	BadExample  string // Code showing the anti-pattern
	GoodExample string // Code showing the correct pattern
	Fix         string // How to fix violations (when not obvious)
}

RuleDef is a project-level rule definition.

func GetAll

func GetAll() []RuleDef

GetAll returns all registered rules.

func GetByGroup

func GetByGroup(group string) []RuleDef

GetByGroup returns all rules in a specific group.

func GetByID

func GetByID(id string) (RuleDef, bool)

GetByID returns a rule by its ID.

type SnapshotStore

type SnapshotStore interface {
	GetColumnSnapshot(modelPath string, sourceTable string) (columns []string, runID string, err error)
}

SnapshotStore provides access to column snapshots for schema drift detection. This is a subset of the full state.Store interface.