Skip to content

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

forge.lthn.ai/core/lint

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