Skip to content

Latest commit

 

History

History
217 lines (165 loc) · 4.14 KB

getting-started.md

File metadata and controls

217 lines (165 loc) · 4.14 KB

Getting Started with structlint

structlint validates directory structures and file naming patterns against configurable rules.

Installation

Using Go (Recommended)

go install github.com/AxeForging/structlint@latest
From Binary Downloads

Download from Releases:

Linux:

curl -LO https://github.com/AxeForging/structlint/releases/latest/download/structlint-linux-amd64.tar.gz
tar -xzf structlint-linux-amd64.tar.gz
sudo mv structlint /usr/local/bin/

macOS:

# Intel
curl -LO https://github.com/AxeForging/structlint/releases/latest/download/structlint-darwin-amd64.tar.gz

# Apple Silicon
curl -LO https://github.com/AxeForging/structlint/releases/latest/download/structlint-darwin-arm64.tar.gz

tar -xzf structlint-darwin-*.tar.gz
sudo mv structlint /usr/local/bin/

Windows (PowerShell):

Invoke-WebRequest -Uri "https://github.com/AxeForging/structlint/releases/latest/download/structlint-windows-amd64.zip" -OutFile structlint.zip
Expand-Archive structlint.zip -DestinationPath .
Move-Item structlint.exe C:\Windows\System32\
From Source 
git clone https://github.com/AxeForging/structlint.git
cd structlint
make build
./bin/structlint version

Quick Start

1. Create a Configuration File

# .structlint.yaml
dir_structure:
  allowedPaths:
    - "."
    - "cmd/**"
    - "internal/**"
    - "pkg/**"
    - "test/**"
  disallowedPaths:
    - "vendor/**"
    - "tmp/**"
  requiredPaths:
    - "cmd"

file_naming_pattern:
  allowed:
    - "*.go"
    - "*.yaml"
    - "*.md"
    - "Makefile"
    - ".gitignore"
  disallowed:
    - "*.env*"
    - "*.log"
  required:
    - "go.mod"
    - "README.md"

ignore:
  - ".git"
  - "vendor"
  - "bin"

2. Run Validation

structlint validate

3. View Results

Passing:

--- Validation Summary ---
✓ 42 files/directories passed validation
✗ 0 violations found
🎉 All files and directories comply with the rules!

Failing:

✗ Directory not in allowed list: tmp
✗ Disallowed file naming pattern found: .env.local
✗ Disallowed file naming pattern found: debug.log

--- Validation Summary ---
✓ 39 files/directories passed validation
✗ 3 violations found

Common Use Cases

Validate with Specific Config 
structlint validate --config custom-config.yaml
Generate JSON Report 
structlint validate --json-output report.json

Output:

{
  "successes": 42,
  "failures": 0,
  "errors": []
}
Use in CI/CD Pipeline 
# Exit code 0 = pass, 1 = fail
structlint validate || exit 1
Verbose/Debug Output 
structlint validate --log-level debug
Silent Mode (Scripts) 
if structlint validate --silent; then
  echo "Structure OK"
else
  echo "Structure violations found"
fi

Understanding Configuration

Directory Rules

Field Purpose Example
allowedPaths Only these directories allowed ["cmd/**", "internal/**"]
disallowedPaths These directories forbidden ["vendor/**", "tmp/**"]
requiredPaths These must exist ["cmd", "internal"]

File Rules

Field Purpose Example
allowed Only these files allowed ["*.go", "*.md"]
disallowed These files forbidden ["*.env*", "*.log"]
required At least one must exist ["go.mod", "README.md"]

Ignore

Paths in ignore are completely skipped:

ignore:
  - ".git"
  - "vendor"
  - "node_modules"

Next Steps