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
- Variables
- func CountGoFiles(dir string) int
- func CountPyFiles(dir string) int
- func FindGoPackages(baseDir string, recursive bool) []string
- func FindPyFiles(baseDir string, recursive bool) []string
- func Flycheck(ctx context.Context, filename string) (result, suggestion string, err error)
- func IsLanguageSupported(lang string) bool
- func LanguageFromContext(ctx context.Context) string
- func NormalizePath(path string) (string, bool)
- type CheckResult
- type Checker
- type ClassifiedIssue
- type IssueSeverity
- type IssueStats
Constants ¶
Variables ¶
var EmacsKey = context.ContextKeyType[bool]{}
EmacsKey 用于 context.WithValue 传递 --emacs 选项。 当设置为 true 时,强制使用 Emacs flycheck(而非 dscli 内置实现)。
var LanguageKey = context.ContextKeyType[string]{}
LanguageKey 用于 context.WithValue 传递目标语言。 示例:ctx = context.WithValue(ctx, flycheck.LanguageKey, "python")
Registry maps language identifiers (from parse.GuessLanguage) to their checkers. Add entries here when supporting new languages.
Functions ¶
func FindGoPackages ¶
FindGoPackages 返回给定目录下所有含有 .go 文件的子目录(相对路径)。 如果 recursive 为 true,递归查找所有子目录;否则只查找直接子目录。 同时也会检查 baseDir 本身是否含有 .go 文件。
func FindPyFiles ¶
FindPyFiles 返回给定目录下所有 .py 文件的相对路径。 如果 recursive 为 true,递归查找所有子目录;否则只查找目录本身。
func Flycheck ¶
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 ¶
IsLanguageSupported 返回该语言是否有已注册的检查器。
func LanguageFromContext ¶
LanguageFromContext 从 context 中读取目标语言,若未设置返回空字符串。
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 ¶
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