Incubation request: falco-language #502
Description
Repository: https://github.com/c2ndev/falco-lsp
Motivation
This project provides comprehensive language tooling for Falco security rules, including:
- Go Language Server (LSP) -- Full LSP implementation with code completion, hover, go-to-definition, find references, diagnostics, formatting, and document symbols for
.falco.yaml/.falco.ymlfiles - CLI Tool (
falco-lang) -- Standalone validation and formatting for Falco rules, usable in CI/CD pipelines - VS Code Extension -- Rich editor experience with syntax highlighting, TextMate grammar, snippets, and all LSP features
Why incubation?
Falco currently lacks official language tooling for rule authoring. The only existing editor integration in the ecosystem is flycheck-falco-rules (Emacs, incubating), which provides basic syntax checking. This project goes significantly further:
- Full LSP protocol -- works with any LSP-compatible editor (VS Code, Neovim, Helix, etc.)
- Deep Falco knowledge -- validates conditions against the complete Falco field registry (syscall, k8s_audit, aws_cloudtrail, gcp_auditlog, github, okta), checks macro/list references, validates priorities, sources, and rule structure
- Condition expression parser -- lexer + AST for Falco condition expressions with operator validation, field resolution, and macro expansion
- Code completion -- context-aware completions for block types, properties, field names (with dot-notation), operators, priorities, sources, tags, boolean values, macro/list references
- Formatter -- configurable indentation with check/write/diff modes
Incubation requirements compliance
| Requirement | Status | Details |
|---|---|---|
| At least two maintainers | Partial | @c2ndev (author). Seeking a second maintainer from the community |
| Basic documentation | Met | README, CONTRIBUTING, CHANGELOG, CLI help, VS Code extension README |
| Apache-2.0 license | Met | LICENSE file present, headers on all Go source files |
| OWNERS file | Met | Present in repository root |
| Minimal CI/CD pipelines | Met | 4 GitHub Actions workflows (see below) |
Project maturity
| Metric | Value |
|---|---|
| Go packages | 29, all passing with -race |
| Test coverage | 90%+ on critical packages (completion, hover, definition, references) |
| Linting | 23+ linters via golangci-lint, 0 issues |
| Platforms tested | Ubuntu, macOS, Windows |
| Go versions tested | 1.21, 1.22 |
| Cross-compilation | linux/darwin/windows x amd64/arm64 |
CI/CD pipelines
| Workflow | Trigger | Description |
|---|---|---|
go-tests.yml |
Push/PR on main | Linting, multi-platform/multi-version tests, coverage (Codecov), integration tests against official Falco rules |
build.yml |
Push/PR on main | Cross-platform binary builds, artifact upload |
vscode-extension.yml |
Push/PR on main | Go binary build + Node.js extension build + VSIX packaging |
release.yml |
Tag push (v*) |
Full release: tests, cross-compilation, GitHub Release, VS Code Marketplace + Open VSX publication |
LSP features
| Feature | Supported |
|---|---|
| Code completion | Context-aware: blocks, properties, fields, operators, priorities, sources, tags, booleans, macros, lists |
| Hover | Field descriptions, macro/list definitions with source location |
| Go-to-definition | Macros and lists across files |
| Find references | All usages of macros and lists |
| Diagnostics | YAML structure, required fields, condition validation, field/macro/list resolution, priority/source validation |
| Formatting | Configurable indentation, check/write/diff modes |
| Document symbols | Rules, macros, lists hierarchy |
CLI features
| Command | Description |
|---|---|
falco-lang validate |
Validate files/directories with JSON output, strict mode, multi-file support |
falco-lang format |
Check formatting, write in-place, or show diff |
falco-lang lsp |
Start LSP server (stdio mode) for any editor |
falco-lang version |
Show version and build info |
Ecosystem context
- Scope: Ecosystem (editor tooling, not core runtime)
- Precedent:
flycheck-falco-rules(Emacs syntax checker, incubating since 2022) - Complementary to: falcoctl, rules repo, falco core
Benefits of adoption
- Professional editing experience for rule authors, reducing errors and improving productivity
- CLI enables automated validation in CI/CD pipelines for organizations managing Falco rules
- Under falcosecurity: increased visibility, adoption, and community contributions
- LSP protocol means any editor can benefit, not just VS Code
Proposed maintainers
- @c2ndev (author)
Looking for a second maintainer from the community to meet the two-maintainer requirement for incubation.