core/lint¶
forge.lthn.ai/core/lint is a standalone pattern catalog and code quality toolkit. It ships a YAML-based rule catalog for detecting security issues, correctness bugs, and modernisation opportunities in Go source code. It also provides a full PHP quality assurance pipeline and a suite of developer tooling wrappers.
The library is designed to be embedded into other tools. The YAML rule files are compiled into the binary at build time via go:embed, so there are no runtime file dependencies.
Module Path¶
Requires Go 1.26+.
Quick Start¶
As a Library¶
import (
lint "forge.lthn.ai/core/lint"
lintpkg "forge.lthn.ai/core/lint/pkg/lint"
)
// Load the embedded rule catalog.
cat, err := lint.LoadEmbeddedCatalog()
if err != nil {
log.Fatal(err)
}
// Filter rules for Go, severity medium and above.
rules := cat.ForLanguage("go")
filtered := (&lintpkg.Catalog{Rules: rules}).AtSeverity("medium")
// Create a scanner and scan a directory.
scanner, err := lintpkg.NewScanner(filtered)
if err != nil {
log.Fatal(err)
}
findings, err := scanner.ScanDir("./src")
if err != nil {
log.Fatal(err)
}
// Output results.
lintpkg.WriteText(os.Stdout, findings)
As a CLI¶
# Build the binary
core build # produces ./bin/core-lint
# Scan the current directory with all rules
core-lint lint check
# Scan with filters
core-lint lint check --lang go --severity high ./pkg/...
# Output as JSON
core-lint lint check --format json .
# Browse the catalog
core-lint lint catalog list
core-lint lint catalog list --lang go
core-lint lint catalog show go-sec-001
QA Commands¶
The qa command group provides workflow-level quality assurance:
# Go-focused
core qa watch # Monitor GitHub Actions after a push
core qa review # PR review status with actionable next steps
core qa health # Aggregate CI health across all repos
core qa issues # Intelligent issue triage
core qa docblock # Check Go docblock coverage
# PHP-focused
core qa fmt # Format PHP code with Laravel Pint
core qa stan # Run PHPStan/Larastan static analysis
core qa psalm # Run Psalm static analysis
core qa audit # Audit composer and npm dependencies
core qa security # Security checks (.env, filesystem, deps)
core qa rector # Automated code refactoring
core qa infection # Mutation testing
core qa test # Run Pest or PHPUnit tests
Package Layout¶
| Package | Path | Description |
|---|---|---|
lint (root) |
lint.go |
Embeds YAML catalogs and exposes LoadEmbeddedCatalog() |
pkg/lint |
pkg/lint/ |
Core library: Rule, Catalog, Matcher, Scanner, Report, Complexity, Coverage, VulnCheck, Toolkit |
pkg/detect |
pkg/detect/ |
Project type detection (Go, PHP) by filesystem markers |
pkg/php |
pkg/php/ |
PHP quality tools: format, analyse, audit, security, refactor, mutation, test, pipeline, runner |
cmd/core-lint |
cmd/core-lint/ |
CLI binary (core-lint lint check, core-lint lint catalog) |
cmd/qa |
cmd/qa/ |
QA workflow commands (watch, review, health, issues, docblock, PHP tools) |
catalog/ |
catalog/ |
YAML rule definitions (embedded at compile time) |
Rule Catalogs¶
Three built-in YAML catalogs ship with the module:
| File | Rules | Focus |
|---|---|---|
go-security.yaml |
6 | SQL injection, path traversal, XSS, timing attacks, log injection, secret leaks |
go-correctness.yaml |
7 | Unsynchronised goroutines, silent error swallowing, panics in library code, file deletion |
go-modernise.yaml |
5 | Replace legacy patterns with modern stdlib (slices.Clone, slices.Sort, maps.Keys, errgroup) |
Total: 18 rules across 3 severity tiers (info, medium, high, critical). All rules target Go. The catalog is extensible -- add more YAML files to catalog/ and they will be embedded automatically.
Dependencies¶
Direct dependencies:
| Module | Purpose |
|---|---|
forge.lthn.ai/core/cli |
CLI framework (cli.Main(), command registration, TUI styles) |
forge.lthn.ai/core/go-i18n |
Internationalisation for CLI strings |
forge.lthn.ai/core/go-io |
Filesystem abstraction for registry loading |
forge.lthn.ai/core/go-log |
Structured logging and error wrapping |
forge.lthn.ai/core/go-scm |
Repository registry (repos.yaml) for multi-repo commands |
github.com/stretchr/testify |
Test assertions |
gopkg.in/yaml.v3 |
YAML parsing for rule catalogs |
The pkg/lint sub-package has minimal dependencies (only gopkg.in/yaml.v3 and standard library). The heavier CLI and SCM dependencies live in cmd/.
Licence¶
EUPL-1.2