lint/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

core/lint is a standalone pattern catalog, regex-based code checker, and multi-language QA toolkit. It loads YAML rule definitions and matches them against source files, plus wraps external Go and PHP tooling into structured APIs. Zero framework dependencies — uses forge.lthn.ai/core/cli for CLI scaffolding only.

Build & Development

core go test          # run all tests
core go test ./pkg/lint/...   # run tests for a specific package
core go qa            # full QA pipeline (vet, lint, test)
core build            # produces ./bin/core-lint

Run a single test:

go test -run TestMatcherExcludePattern ./pkg/lint/

Architecture

Three distinct subsystems share this module:

1. Pattern Catalog & Scanner (pkg/lint/)

The core lint engine. YAML rules in catalog/ are embedded at compile time via //go:embed in lint.go and loaded through LoadEmbeddedCatalog().

Data flow: YAML → ParseRules → Catalog → filter by language/severity → NewMatcher (compiles regexes) → Scanner.ScanDir/ScanFile → []Finding → output as text/JSON/JSONL via report.go.

Key types:

• Rule — parsed from YAML, validated with Validate(). Only detection: "regex" rules are matched; other detection types are stored but skipped by Matcher.
• Matcher — holds pre-compiled regexp.Regexp for each rule's pattern and optional exclude_pattern. Matches line-by-line.
• Scanner — walks directory trees, auto-detects language from file extension (extensionMap), skips vendor/node_modules/.git/testdata/.core.
• Finding — a match result with rule ID, file, line, severity, and fix suggestion.

2. Go Dev Toolkit (pkg/lint/tools.go, complexity.go, coverage.go, vulncheck.go)

Structured Go APIs wrapping external tools (go vet, govulncheck, gocyclo, gitleaks, git). The Toolkit type executes subprocesses and parses their output into typed structs (ToolFinding, Vulnerability, CoverageReport, RaceCondition, etc.).

complexity.go provides native AST-based cyclomatic complexity analysis (no external tools needed) via AnalyseComplexity.

coverage.go provides CoverageStore for persisting and comparing coverage snapshots over time, detecting regressions.

vulncheck.go parses govulncheck -json NDJSON output into VulnFinding structs.

3. PHP QA Toolchain (pkg/php/, pkg/detect/, cmd/qa/)

Wraps PHP ecosystem tools (Pint, PHPStan/Larastan, Psalm, Rector, Infection, PHPUnit/Pest, composer audit). pkg/detect/ identifies project type by filesystem markers (go.mod → Go, composer.json → PHP).

pkg/php/pipeline.go defines a staged QA pipeline: quick (audit, fmt, stan) → standard (+psalm, test) → full (+rector, infection).

pkg/php/runner.go builds process.RunSpec entries with dependency ordering (After field) for the core/go-process runner.

CLI Entry Points

• cmd/core-lint/main.go — core-lint lint check and core-lint lint catalog commands
• cmd/qa/ — core qa subcommands registered via init() → cli.RegisterCommands. Go-focused (watch, review, health, issues, docblock) and PHP-focused (fmt, stan, psalm, audit, security, rector, infection, test).

Rule Schema

Each YAML file in catalog/ contains an array of rules:

- id: go-sec-001            # unique identifier
  title: "..."              # human-readable title
  severity: high            # info | low | medium | high | critical
  languages: [go]           # file extensions mapped via extensionMap
  tags: [security]          # free-form tags
  pattern: 'regex'          # Go regexp syntax
  exclude_pattern: 'regex'  # optional, skips matching lines/files
  fix: "..."                # suggested fix text
  detection: regex          # only "regex" is actively matched
  auto_fixable: false
  example_bad: '...'
  example_good: '...'

Rules are validated on load — Validate() checks required fields and compiles regex patterns.

Coding Standards

• UK English (e.g. Analyse, Summarise, Colour)
• All functions have typed params/returns
• Tests use testify (assert/require)
• Licence: EUPL-1.2