linter

Documentation

Overview

Package linter checks a cheatmd cheats directory for problems.

It runs three categories of checks:

1. DSL syntax: each line inside a `<!-- cheat -->` block must be one of `var`/`if`/`fi`/`export`/`import`, blank, or a `#` comment. Var names must be valid; `if` must have a matching `fi`.
2. References: every `import foo` must resolve to an `export foo` defined somewhere in the index. Duplicate `export` names are flagged. `$var`/`<var>` references in commands should be declared (in a cheat block or imported module), and undeclared references are warnings.
3. Structural: empty `##` headers, missing code blocks, duplicate cheat headers across the linted input.

Index

• type Finding
  • func Lint(path string) ([]Finding, error)
  • func LintWithConfig(path string, cfg config.Config) ([]Finding, error)
  • func (f Finding) Format() string
• type Ref
• type RefKind
• type Severity
  • func (s Severity) String() string

Types

type Finding

type Finding struct {
	File     string
	Line     int // 1-indexed; 0 means "file-level" (no specific line)
	Column   int // 1-indexed; 0 means "line-level"
	Severity Severity
	Message  string
}

Finding is one issue surfaced by the linter.

func Lint

func Lint(path string) ([]Finding, error)

Lint walks path (file or directory), parses every markdown file, and returns all findings sorted by file/line.

func LintWithConfig

func LintWithConfig(path string, cfg config.Config) ([]Finding, error)

LintWithConfig walks path (file or directory), parses every markdown file, and returns findings using cfg for runtime-sensitive checks such as variable syntax and declaration-free prompting.

func (Finding) Format

func (f Finding) Format() string

Format renders the finding in GCC-style:

file:line:col: severity: message

Line/col are omitted (replaced with 1) when not known.

type Ref

type Ref struct {
	Name   string
	Kind   RefKind
	Line   int
	Column int
}

Ref represents a single parsed reference (like a variable or an import) within the AST.

type RefKind

type RefKind int

RefKind enumerates the different types of semantic references found in cheatmd Markdown.

const (
	RefShellParam RefKind = iota
	RefPowerShellParam
	RefAngleTemplate
	RefPerlParam
)

type Severity

type Severity int

Severity classifies a finding.

const (
	// SeverityError indicates a genuine problem: malformed DSL, missing
	// import target, duplicate export, etc.
	SeverityError Severity = iota
	// SeverityWarning indicates a recommendation or potential issue:
	// undeclared variables, duplicate headers across the linted input.
	SeverityWarning
)

func (Severity) String

func (s Severity) String() string

String returns the lowercase name of the severity ("error" or "warning").