141 lines
4.9 KiB
Markdown
141 lines
4.9 KiB
Markdown
---
|
|
title: core/lint
|
|
description: Pattern catalog, regex-based code checker, and quality assurance toolkit for Go and PHP projects
|
|
---
|
|
|
|
# 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
|
|
|
|
```go
|
|
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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|