flycheck

package
v0.8.1 Latest Latest
Warning

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

Go to latest
Published: May 20, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package flycheck provides on-the-fly syntax checking for code files, inspired by Emacs flycheck. It detects language from file extension, finds the appropriate checker, runs it, and returns results.

Starting with Go + staticcheck, the architecture supports adding more languages and checkers incrementally.

Index

Constants

View Source
const (
	// DefaultTimeout is the default time limit for a checker run.
	DefaultTimeout = 15 * time.Second
)

Variables

View Source
var EmacsKey = context.ContextKeyType[bool]{}

EmacsKey 用于 context.WithValue 传递 --emacs 选项。 当设置为 true 时,强制使用 Emacs flycheck(而非 dscli 内置实现)。

View Source
var LanguageKey = context.ContextKeyType[string]{}

LanguageKey 用于 context.WithValue 传递目标语言。 示例:ctx = context.WithValue(ctx, flycheck.LanguageKey, "python")

View Source
var Registry = map[string][]Checker{
	"go":     {goStaticcheck},
	"python": {pythonRuff},
}

Registry maps language identifiers (from parse.GuessLanguage) to their checkers. Add entries here when supporting new languages.

Functions

func CountGoFiles

func CountGoFiles(dir string) int

CountGoFiles 统计目录下的 .go 文件数量。

func CountPyFiles

func CountPyFiles(dir string) int

CountPyFiles 统计目录下的 .py 文件数量(递归)。

func FindGoPackages

func FindGoPackages(baseDir string, recursive bool) []string

FindGoPackages 返回给定目录下所有含有 .go 文件的子目录(相对路径)。 如果 recursive 为 true,递归查找所有子目录;否则只查找直接子目录。 同时也会检查 baseDir 本身是否含有 .go 文件。

func FindPyFiles

func FindPyFiles(baseDir string, recursive bool) []string

FindPyFiles 返回给定目录下所有 .py 文件的相对路径。 如果 recursive 为 true,递归查找所有子目录;否则只查找目录本身。

func Flycheck

func Flycheck(ctx context.Context, filename string) (result, suggestion string, err error)

Flycheck runs syntax checkers on a file and returns any issues found.

Uses context.ProjectRoot as the working directory for running checkers.

Returns:

  • result: checker output containing issues (empty if no issues)
  • suggestion: install hints or fix suggestions (only when err != nil)
  • err: system error (checker not found, timeout, etc.), nil if check succeeded

If the language is not supported, returns ("", "", nil) — silently skipped.

func IsLanguageSupported

func IsLanguageSupported(lang string) bool

IsLanguageSupported 返回该语言是否有已注册的检查器。

func LanguageFromContext

func LanguageFromContext(ctx context.Context) string

LanguageFromContext 从 context 中读取目标语言,若未设置返回空字符串。

func NormalizePath

func NormalizePath(path string) (string, bool)

NormalizePath 规范化 flycheck 路径,同时检测递归模式。 返回 (cleanPath, recursive)。

Types

type CheckResult

type CheckResult struct {
	Path string // 规范化后的路径

	Language  string // 检测到的语言("go", "python", …)
	Mode      string // "package"(Go 包检查)或 "file"(单文件检查)
	Supported bool   // 该语言是否有注册的检查器

	// Go 包检查结果
	Issues      []ClassifiedIssue // 分类后的问题
	Stats       IssueStats        // 问题统计
	NPkgs       int               // 检查的包数
	NFiles      int               // 检查的文件数
	FailedPkgs  []string          // 检查失败的包(相对路径)
	FailedInfos []string          // 失败包的简要错误信息(与 FailedPkgs 一一对应)

	// 非 Go 文件检查结果
	RawOutput string // 原始检查器输出

	// 通用
	Suggestion string // 安装提示等建议信息(仅当 err != nil 时有意义)
}

CheckResult 封装一次 flycheck 检查的完整结果。 调用方根据 Mode / Language / Supported 字段区别处理。

func CheckPath

func CheckPath(ctx context.Context, path string) (*CheckResult, error)

CheckPath 智能检查任意路径(文件或目录),自动识别语言并选择合适的检查器。

路径处理:

  • 自动规范化(去除 "./" 前缀、清理冗余分隔符)
  • 识别递归模式(路径后缀 "...")
  • 自动判断文件 vs 目录

语言识别:

  • 文件:从扩展名自动识别(parse.GuessLanguage)
  • 目录:默认查找 Go 包;可通过 context.WithValue(LanguageKey, lang) 指定语言

选项:

  • --emacs: 通过 context.WithValue(EmacsKey, true) 强制使用 Emacs flycheck
  • 未设置时,自动检测 INSIDE_EMACS/EMACS 环境变量

返回 CheckResult,调用方根据 Mode / Language / Supported 字段区别处理。

type Checker

type Checker struct {
	Name        string // e.g. "go-staticcheck"
	Command     string // e.g. "staticcheck"
	InstallHint string // Human-readable install instruction
	// BuildArgs builds command-line arguments for checking the given file.
	// filename is project-relative, project root is taken from context.ProjectRoot.
	BuildArgs func(filename string) []string
	// BuildDirArgs builds command-line arguments for checking a directory.
	// If nil, directory checking falls back to BuildArgs (may not work for all checkers).
	BuildDirArgs func(dir string) []string
}

Checker defines a syntax checker for a specific language. Each language can have multiple checkers (e.g. go: staticcheck, go vet; python: ruff, flake8).

type ClassifiedIssue

type ClassifiedIssue struct {
	Severity IssueSeverity
	Line     string
}

ClassifiedIssue holds a single checker issue with its severity.

func ClassifyIssues

func ClassifyIssues(raw string) []ClassifiedIssue

ClassifyIssues splits raw checker output into classified issues, filtering out summary/boilerplate lines (e.g. ruff's "Found N errors").

func FlycheckDir

func FlycheckDir(ctx context.Context, lang, dir string) (result string, rawIssues []ClassifiedIssue, suggestion string, err error)

FlycheckDir runs checkers on a project-relative directory for the given language.

Returns:

  • result: formatted checker output (empty if no issues)
  • rawIssues: classified issues for stats aggregation (empty if no issues)
  • suggestion: install hints or fix suggestions (only when err != nil)
  • err: system error (checker not found, timeout, etc.)

type IssueSeverity

type IssueSeverity int

IssueSeverity classifies the severity of a checker issue.

const (
	SevError      IssueSeverity = iota // ❌ compile/syntax error
	SevWarning                         // ⚠️ lint warning
	SevSuggestion                      // 💡 improvement suggestion
)

func (IssueSeverity) String

func (s IssueSeverity) String() string

String returns the emoji prefix for the severity.

type IssueStats

type IssueStats struct {
	Errors      int
	Warnings    int
	Suggestions int
}

IssueStats summarizes classified issues.

func CountStats

func CountStats(issues []ClassifiedIssue) IssueStats

CountStats computes stats from classified issues.

Source Files

  • checkpath.go
  • emacs.go
  • flycheck.go

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL