### Run a Minimal Linting Example

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/README.md

A complete example showing how to initialize a logger, build a ruleset, and apply it to an OpenAPI specification file.

```go
package main

import (
    "fmt"
    "log/slog"
    "os"
    
    "github.com/daveshanley/vacuum/motor"
    "github.com/daveshanley/vacuum/rulesets"
)

func main() {
    logger := slog.New(slog.NewTextHandler(os.Stderr, nil))
    builder := rulesets.BuildDefaultRuleSetsWithLogger(logger)
    rs := builder.GenerateOpenAPIRecommendedRuleSet()
    
    spec, _ := os.ReadFile("openapi.yaml")
    
    result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
        RuleSet: rs,
        Spec:    spec,
        SpecFileName: "openapi.yaml",
    })
    
    fmt.Printf("Found %d errors\n", result.Results.GetErrorCount())
}
```

--------------------------------

### Install vacuum via curl

Source: https://github.com/daveshanley/vacuum/blob/main/README.md

Downloads and executes the installation script directly.

```bash
curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh
```

--------------------------------

### Install vacuum via Homebrew

Source: https://github.com/daveshanley/vacuum/blob/main/README.md

Installs the vacuum binary using the official Homebrew tap.

```bash
brew install --cask daveshanley/vacuum/vacuum
```

--------------------------------

### Install Vacuum Library

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/GETTING_STARTED.md

Use the Go toolchain to fetch the Vacuum package.

```bash
go get github.com/daveshanley/vacuum
```

--------------------------------

### Initialize FetchConfig

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/types.md

Example instantiation of the FetchConfig struct with TLS and timeout settings.

```go
config := &config.FetchConfig{
    HTTPClientConfig: config.HTTPClientConfig{
        CertFile: "/path/to/cert.pem",
        KeyFile:  "/path/to/key.pem",
    },
    AllowPrivateNetworks: false,
    AllowHTTP:            false,
    Timeout:              30 * time.Second,
}
```

--------------------------------

### Create AsyncAPI context example

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/asyncapi.md

Demonstrates reading a file and initializing a new context for linting.

```go
import (
    "github.com/daveshanley/vacuum/asyncapi"
    "github.com/pb33f/libasyncapi"
)

// Read AsyncAPI spec
spec, _ := os.ReadFile("asyncapi.yaml")

// Create context
ctx, err := asyncapi.NewContext(
    spec,
    "asyncapi.yaml",
    libasyncapi.NewDocumentConfiguration(),
)
if err != nil {
    fmt.Printf("Failed to create AsyncAPI context: %v\n", err)
    return
}

// Use context in rules
fmt.Printf("Spec version: %s\n", ctx.SpecInfo.Version)
```

--------------------------------

### Install vacuum via yarn

Source: https://github.com/daveshanley/vacuum/blob/main/README.md

Installs the vacuum package globally using yarn.

```bash
yarn global add @quobix/vacuum
```

--------------------------------

### Install vacuum in CI/CD with GitHub Token

Source: https://github.com/daveshanley/vacuum/blob/main/README.md

Uses a GitHub token to bypass API rate limits during installation in automated environments.

```bash
# Using repository token (GitHub Actions)
GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh

# Using personal access token
GITHUB_TOKEN=your_github_token curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh
```

--------------------------------

### Install vacuum via npm

Source: https://github.com/daveshanley/vacuum/blob/main/README.md

Installs the vacuum package globally using npm.

```bash
npm i -g @quobix/vacuum
```

--------------------------------

### CreateCustomHTTPClient usage

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/utils.md

Example of creating a custom HTTP client and handling potential configuration errors.

```go
httpClient, err := vacuumUtils.CreateCustomHTTPClient(config)
if err != nil {
    fmt.Printf("Failed to create HTTP client: %v\n", err)
    return
}

// Use client for downloading remote specs
```

--------------------------------

### Validate Schema Examples in Go

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/parser.md

Validates multiple example nodes against a loaded schema and collects results.

```go
// Load the schema from spec
schema, _ := parser.ConvertNodeIntoJSONSchema(schemaNode, index)

// Validate each example
for _, exampleNode := range exampleNodes {
    isValid, errors := parser.ValidateNodeAgainstSchema(
        ruleContext,
        schema,
        exampleNode,
        false,
    )
    
    if !isValid {
        for _, err := range errors {
            results = append(results, model.RuleFunctionResult{
                Message:  fmt.Sprintf("Invalid example: %s", err.Message),
                Path:     path,
                RuleId:   "invalid-example",
            })
        }
    }
}
```

--------------------------------

### Configure owasp-array-limit Rule

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/functions.md

Example YAML configuration for applying the owasp-array-limit function to a schema.

```yaml
rules:
  owasp-array-limit:
    given: $.components.schemas[*].properties[?@.type=='array']
    then:
      function: owaspArrayLimit
```

--------------------------------

### Casing Rule Usage

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/functions.md

Example YAML configuration for applying the casing function.

```yaml
rules:
  camel-case-properties:
    given: $.components.schemas[*].properties[*]~
    then:
      function: casing
      functionOptions:
        type: camelCase
```

--------------------------------

### Pattern Rule Usage

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/functions.md

Example YAML configuration for applying the pattern function.

```yaml
rules:
  kebab-case-paths:
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^/[a-z0-9-/]*$"
```

--------------------------------

### ApplyRulesToRuleSetWithOptions Usage Example

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/motor.md

Demonstrates configuring execution options such as reference resolution before applying the ruleset.

```go
opts := &motor.ExecutionOptions{
    ResolveAllRefs:       true,  // Force resolved execution for all rules
    NestedRefsDocContext: true,  // Resolve nested refs from context
}

result := motor.ApplyRulesToRuleSetWithOptions(execution, opts)
```

--------------------------------

### Clone Vacuum Repository and Navigate to Plugin Directory

Source: https://github.com/daveshanley/vacuum/blob/main/plugin/sample/README.md

Clone the Vacuum repository and change the current directory to the plugin sample directory. This is the first step to start working with custom plugins.

```bash
git clone https://github.com/daveshanley/vacuum.git && cd vacuum/plugin/sample 
```

--------------------------------

### ApplyRulesToRuleSet Usage Example

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/motor.md

Demonstrates loading a ruleset and specification, executing the linting process, and iterating over the resulting violations.

```go
import (
    "github.com/daveshanley/vacuum/motor"
    "github.com/daveshanley/vacuum/rulesets"
)

// Load a ruleset
rs := rulesets.BuildDefaultRuleSetsWithLogger(logger).
    GenerateOpenAPIRecommendedRuleSet()

// Load specification
specBytes, _ := os.ReadFile("openapi.yaml")

// Execute linting
result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
    RuleSet:      rs,
    SpecFileName: "openapi.yaml",
    Spec:         specBytes,
})

// Process results
for _, violation := range result.Results {
    fmt.Printf("Rule %s: %s\n", violation.RuleId, violation.Message)
}
```

--------------------------------

### Configure Path Matching Patterns

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/configuration.md

Examples of exact paths and JSONPath patterns for ignore rules.

```yaml
operation-operationId:
  - $.paths['/users'].get              # Exact path
  - $.paths['/posts']['*']             # All operations on /posts
  - $.paths['/*'].post                 # POST operations on all paths
  - $.components.schemas['*']          # All schemas
```

--------------------------------

### Build and Lint HTML Report UI Package

Source: https://github.com/daveshanley/vacuum/blob/main/AGENTS.md

Navigate to the UI package directory, install dependencies, build the UI, and run linting. Use for html-report/ui package-only changes.

```bash
cd html-report/ui
npm ci
npm run build
npm run lint
```

--------------------------------

### ShouldUseCustomHTTPClient usage

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/utils.md

Example of conditionally creating a custom HTTP client based on configuration settings.

```go
if vacuumUtils.ShouldUseCustomHTTPClient(config) {
    httpClient, _ := vacuumUtils.CreateCustomHTTPClient(config)
    // Use custom client
}
```

--------------------------------

### Upgrade Vacuum

Source: https://github.com/daveshanley/vacuum/blob/main/README.md

Update the vacuum installation to the latest version.

```bash
vacuum upgrade
```

--------------------------------

### Alphabetical Rule Usage

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/functions.md

Example YAML configuration for applying the alphabetical function.

```yaml
rules:
  tags-alphabetical:
    given: $.tags[*]
    then:
      function: alphabetical
      functionOptions:
        keyedBy: name
```

--------------------------------

### CreateRemoteURLHandler usage

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/utils.md

Example of integrating a custom HTTP client into document configuration for remote reference fetching.

```go
httpClient, _ := vacuumUtils.CreateCustomHTTPClient(config)
urlHandler := vacuumUtils.CreateRemoteURLHandler(httpClient)

docConfig := datamodel.NewDocumentConfiguration()
docConfig.RemoteURLHandler = urlHandler

// Document will use custom client for remote references
```

--------------------------------

### Arch Linux PKGBUILD for Custom Version

Source: https://github.com/daveshanley/vacuum/blob/main/BUILD_PACKAGING.md

Example of setting custom version, commit, and date for vacuum build within an Arch Linux PKGBUILD file using ldflags.

```bash
pkgver="0.18.6"
_commit="a535d6c"
_date=$(date '+%a, %d %b %Y %H:%M:%S %Z')

go build -ldflags "-linkmode=external \
    -X main.version=$pkgver \
    -X main.commit=$_commit \
    -X 'main.date=$_date'" \
    -o vacuum
```

--------------------------------

### Initialize RuleSets with Logger

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/rulesets.md

Example usage of BuildDefaultRuleSetsWithLogger to initialize a builder and generate a recommended OpenAPI ruleset.

```go
import (
    "log/slog"
    "os"
    "github.com/daveshanley/vacuum/rulesets"
)

logger := slog.New(slog.NewTextHandler(os.Stderr, nil))
builder := rulesets.BuildDefaultRuleSetsWithLogger(logger)

// Generate a ruleset
rs := builder.GenerateOpenAPIRecommendedRuleSet()
```

--------------------------------

### GitHub Actions workflow step for vacuum

Source: https://github.com/daveshanley/vacuum/blob/main/README.md

Configures the vacuum installation within a GitHub Actions workflow with an environment token.

```yaml
- name: Install vacuum
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # Increases rate limit from 60 to 5000 requests/hour
  run: |
    curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh
```

--------------------------------

### Initialize IgnoredItems

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/model.md

Example usage of IgnoredItems to suppress specific rule violations at defined paths.

```go
ignored := model.IgnoredItems{
    "operation-operationId": {"$.paths['/users'].get"},
    "info-description":      {"$"},
}
// Rule violations at these paths are suppressed
```

--------------------------------

### Get Options as String Map

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/model.md

Returns cached options as a string map, supporting both Spectral and Vacuum formats.

```go
func (ctx *RuleFunctionContext) GetOptionsStringMap() map[string]string
```

--------------------------------

### Nix Package for Custom Version

Source: https://github.com/daveshanley/vacuum/blob/main/BUILD_PACKAGING.md

Example of configuring ldflags for a Nix package to embed custom version, commit, and date information into the vacuum binary.

```nix
buildGoModule {
  pname = "vacuum";
  version = "0.18.6";

  ldflags = [
    "-X main.version=${version}"
    "-X main.commit=${src.rev or \"unknown\"}"
    "-X main.date=1970-01-01T00:00:00Z"
  ];
}
```

--------------------------------

### Define Custom Rules with Extends

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/rulesets.md

Example of extending the recommended ruleset while overriding specific rule severities and adding custom pattern-based rules.

```yaml
# my-ruleset.yaml
extends:
  - recommended  # Start with recommended rules
rules:
  info-contact:
    severity: error  # Make contact required (was warn)
  
  custom-rule-1:
    description: Enforce specific naming
    message: All endpoints must use kebab-case
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^/[a-z0-9-/]*$"
```

--------------------------------

### Debian Package Makefile for Custom Version

Source: https://github.com/daveshanley/vacuum/blob/main/BUILD_PACKAGING.md

Example Makefile snippet for a Debian package to build vacuum with version, commit, and date information dynamically fetched from git and dpkg-parsechangelog.

```makefile
VERSION := $(shell dpkg-parsechangelog -S Version)
COMMIT := $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
DATE := $(shell date -R)

build:
	go build -ldflags "-X main.version=$(VERSION) \
		-X main.commit=$(COMMIT) \
		-X 'main.date=$(DATE)'" \
		-o vacuum
```

--------------------------------

### Initialize HTTPClientConfig

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/utils.md

Demonstrates initializing the configuration and applying it to a rule set execution.

```go
config := vacuumUtils.HTTPClientConfig{
    CertFile: "/etc/ssl/certs/client.pem",
    KeyFile:  "/etc/ssl/private/client.key",
    CAFile:   "/etc/ssl/certs/ca-bundle.pem",
    Insecure: false,
}

result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
    Spec: spec,
    HTTPClientConfig: config,
})
```

--------------------------------

### Using Built-in Functions

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/functions.md

Demonstrates initializing the function registry and retrieving specific functions.

```go
import (
    "github.com/daveshanley/vacuum/functions"
)

// Get all functions
funcs := functions.MapBuiltinFunctions()

// Find a specific function
defined := funcs.FindFunction("defined")
if defined != nil {
    schema := defined.GetSchema()
    fmt.Printf("Function: %s\n", schema.Name)
}

// Get all functions
allFuncs := funcs.GetAllFunctions()
fmt.Printf("Registered %d functions\n", len(allFuncs))
```

--------------------------------

### Apply FetchConfig in RuleSetExecution

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/configuration.md

Demonstrates initializing FetchConfig and applying it to a RuleSetExecution.

```go
fetchConfig := &vacuumUtils.FetchConfig{
    HTTPClientConfig: vacuumUtils.HTTPClientConfig{
        Insecure: false,
    },
    AllowPrivateNetworks: true,  // Allow internal APIs
    AllowHTTP:            false, // Require HTTPS
    Timeout:              30 * time.Second,
}

result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
    RuleSet:     rs,
    Spec:        spec,
    FetchConfig: fetchConfig,
})
```

--------------------------------

### Lint Specification Programmatically

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/GETTING_STARTED.md

Demonstrates the full workflow of initializing a logger, building a ruleset, reading a specification file, and applying linting rules.

```go
package main

import (
    "fmt"
    "log/slog"
    "os"
    
    "github.com/daveshanley/vacuum/motor"
    "github.com/daveshanley/vacuum/rulesets"
)

func main() {
    // 1. Create logger
    logger := slog.New(slog.NewTextHandler(os.Stderr, nil))
    
    // 2. Build ruleset
    builder := rulesets.BuildDefaultRuleSetsWithLogger(logger)
    rs := builder.GenerateOpenAPIRecommendedRuleSet()
    
    // 3. Read specification
    spec, err := os.ReadFile("openapi.yaml")
    if err != nil {
        fmt.Printf("Failed to read spec: %v\n", err)
        return
    }
    
    // 4. Execute linting
    result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
        RuleSet:      rs,
        SpecFileName: "openapi.yaml",
        Spec:         spec,
    })
    
    // 5. Process results
    fmt.Printf("Violations found:\n")
    fmt.Printf("  Errors: %d\n", result.Results.GetErrorCount())
    fmt.Printf("  Warnings: %d\n", result.Results.GetWarningCount())
    fmt.Printf("  Info: %d\n", result.Results.GetInfoCount())
    
    for _, violation := range result.Results {
        fmt.Printf("\n[%s] %s\n", violation.RuleId, violation.Message)
        fmt.Printf("  Path: %s\n", violation.Path)
        fmt.Printf("  Severity: %s\n", violation.RuleSeverity)
    }
}
```

--------------------------------

### Configure TLS-Secured Remote Spec Fetching in Go

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/utils.md

Demonstrates how to initialize a custom HTTP client with TLS certificates and apply it to a linting execution using the vacuum motor.

```go
package main

import (
    "fmt"
    "log/slog"
    "os"
    
    "github.com/daveshanley/vacuum/motor"
    "github.com/daveshanley/vacuum/rulesets"
    vacuumUtils "github.com/daveshanley/vacuum/utils"
)

func main() {
    // 1. Configure TLS
    httpConfig := vacuumUtils.HTTPClientConfig{
        CertFile: "/path/to/client.crt",
        KeyFile:  "/path/to/client.key",
        CAFile:   "/path/to/ca.crt",
        Insecure: false,
    }
    
    // 2. Create HTTP client
    httpClient, err := vacuumUtils.CreateCustomHTTPClient(httpConfig)
    if err != nil {
        fmt.Printf("Failed to create HTTP client: %v\n", err)
        return
    }
    
    // 3. Build ruleset
    logger := slog.New(slog.NewTextHandler(os.Stderr, nil))
    builder := rulesets.BuildDefaultRuleSetsWithLogger(logger)
    rs := builder.GenerateOpenAPIRecommendedRuleSet()
    
    // 4. Read spec (could also be remote with TLS)
    spec, _ := os.ReadFile("api.yaml")
    
    // 5. Configure fetch for custom functions
    fetchConfig := &vacuumUtils.FetchConfig{
        HTTPClientConfig:     httpConfig,
        AllowPrivateNetworks: true,
        AllowHTTP:            false,
        Timeout:              30 * time.Second,
    }
    
    // 6. Execute linting with TLS support
    result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
        RuleSet:          rs,
        Spec:             spec,
        SpecFileName:     "api.yaml",
        HTTPClientConfig: httpConfig,
        FetchConfig:      fetchConfig,
        Base:             "https://api.example.com/",
        AllowLookup:      true,
    })
    
    fmt.Printf("Violations: %d errors, %d warnings\n",
        result.Results.GetErrorCount(),
        result.Results.GetWarningCount())
}
```

--------------------------------

### Execute Standard Linting Workflow

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/rulesets.md

Demonstrates the full lifecycle of building a ruleset, loading a specification, and processing linting results.

```go
// 1. Create builder
logger := slog.New(slog.NewTextHandler(os.Stderr, nil))
builder := rulesets.BuildDefaultRuleSetsWithLogger(logger)

// 2. Load recommended ruleset
rs := builder.GenerateOpenAPIRecommendedRuleSet()

// 3. Load spec
spec, _ := os.ReadFile("spec.yaml")

// 4. Execute linting
result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
    RuleSet:      rs,
    Spec:         spec,
    SpecFileName: "spec.yaml",
})

// 5. Process results
fmt.Printf("Found %d errors, %d warnings\n", 
    result.Results.GetErrorCount(),
    result.Results.GetWarningCount())
```

--------------------------------

### Build with HTML Report Support

Source: https://github.com/daveshanley/vacuum/blob/main/BUILD_PACKAGING.md

Builds the vacuum binary with HTML report support. Requires UI assets to be generated first.

```bash
./scripts/build-ui-assets.sh
go build -tags html_report_ui
```

--------------------------------

### Define oasExampleSchema rule

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/functions.md

Defines the Go struct for validating that examples conform to their schemas.

```go
type ExamplesSchema struct{}
```

--------------------------------

### Build with Partial ldflags (Version and Commit)

Source: https://github.com/daveshanley/vacuum/blob/main/BUILD_PACKAGING.md

Builds the vacuum binary setting only the version and commit information. Date will default to the current build time.

```bash
go build -ldflags "-X main.version=v0.18.6 -X main.commit=a535d6c" -o vacuum
```

--------------------------------

### Truthy Rule Usage

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/functions.md

Example YAML configuration for applying the truthy function to a field.

```yaml
rules:
  info-contact:
    given: $.info.contact
    then:
      function: truthy
      field: name
```

--------------------------------

### Implement Auto-Fix function

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/model.md

Example implementation of an AutoFixFunction that renames an enum field to x-extensible-enum.

```go
func fixEnumToExtensibleEnum(
    node *yaml.Node,
    document *yaml.Node,
    context *model.RuleFunctionContext,
) (*yaml.Node, error) {
    if node.Kind != yaml.MappingNode {
        return node, nil
    }
    
    // Find and rename "enum" field to "x-extensible-enum"
    for i := 0; i < len(node.Content); i += 2 {
        if i+1 >= len(node.Content) {
            break
        }
        if node.Content[i].Value == "enum" {
            node.Content[i].Value = "x-extensible-enum"
            return node, nil
        }
    }
    return node, nil
}
```

--------------------------------

### Configure Custom Filesystem

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/configuration.md

Injects a custom filesystem implementation for resolving local file references.

```go
execution := &motor.RuleSetExecution{
    RolodexFS: customFS,  // Use custom FS for local file refs
}
```

--------------------------------

### Recursive Schema Validation in Go

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/parser.md

Example of a recursive function to validate schema hierarchies.

```go
func validateSchemaHierarchy(
    ctx *model.RuleFunctionContext,
    schema *highBase.Schema,
    node *yaml.Node,
) bool {
    // Validate at current level
    valid, errors := parser.ValidateNodeAgainstSchema(ctx, schema, node, false)
    if !valid {
        for _, err := range errors {
            fmt.Printf("Error at %s: %s\n", err.Path, err.Message)
        }
        return false
    }
    
    // Could recursively validate nested schemas
    return true
}
```

--------------------------------

### Get Rule Severity as Integer

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/model.md

Retrieves the severity level as an integer for sorting purposes.

```go
func (r *Rule) GetSeverityAsIntValue() int
```

--------------------------------

### Build with Partial ldflags (Version Only)

Source: https://github.com/daveshanley/vacuum/blob/main/BUILD_PACKAGING.md

Builds the vacuum binary setting only the version information. Commit will default to 'unknown' and date to the current build time.

```bash
go build -ldflags "-X main.version=v0.18.6" -o vacuum
```

--------------------------------

### Define asyncApiMessageExamples rule

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/functions.md

Defines the Go struct for validating that AsyncAPI message examples are present.

```go
type MessageExamples struct{}
```

--------------------------------

### Use Ignore Files via CLI

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/configuration.md

Demonstrates how to pass an ignore file to the vacuum CLI.

```go
// CLI
vacuum lint --ignore-file .vacuumignore spec.yaml

// Programmatically - ignore files are processed by the CLI, not the API
// Load and parse ignore file, then pass to custom ignore logic
```

--------------------------------

### Initialize NewContext

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/asyncapi.md

Constructor function signature for creating a new AsyncAPI context.

```go
func NewContext(
    spec []byte,
    specFileName string,
    config *libasyncapi.DocumentConfiguration,
) (*Context, error)
```

--------------------------------

### Format and Test Go Files

Source: https://github.com/daveshanley/vacuum/blob/main/AGENTS.md

Run gofmt to format changed Go files and then execute all Go tests.

```bash
gofmt -w <changed-go-files>
go test ./...
```

--------------------------------

### Integration with CI/CD for Dynamic Versioning

Source: https://github.com/daveshanley/vacuum/blob/main/BUILD_PACKAGING.md

Builds the vacuum binary in a CI/CD environment, dynamically generating version, commit, and date information from git commands and setting them via ldflags.

```bash
VERSION=$(git describe --tags --always)
COMMIT=$(git rev-parse --short HEAD)
DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

go build -ldflags "-X main.version=${VERSION} \
    -X main.commit=${COMMIT} \
    -X main.date=${DATE}" \
    -o vacuum
```

--------------------------------

### Build UI Assets and Test with HTML Report

Source: https://github.com/daveshanley/vacuum/blob/main/AGENTS.md

Build UI assets, run Go tests with the html_report_ui tag, and build the main project. Use for official-build behavior or changes touching html-report.

```bash
./scripts/build-ui-assets.sh
go test -tags html_report_ui ./...
make build
```

--------------------------------

### Accessing RuleResultSet data

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/model.md

Example usage for counting violations, iterating through results, and checking for truncated paths.

```go
// Count violations by severity
fmt.Printf("Errors: %d, Warnings: %d, Info: %d, Hints: %d\n",
    resultSet.GetErrorCount(),
    resultSet.GetWarningCount(),
    resultSet.GetInfoCount(),
    resultSet.GetHintCount())

// Iterate violations
for _, result := range resultSet.Results {
    fmt.Printf("%s at %s: %s\n", 
        result.RuleId, result.Path, result.Message)
}

// Check for truncated paths (multi-file specs)
if resultSet.HasTruncatedPaths() {
    fmt.Println("Some resolved aliases were limited for large specs")
}
```

--------------------------------

### Configure Logging

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/configuration.md

Sets up a structured logger and configures silence settings for the execution.

```go
logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
    Level: slog.LevelDebug,
}))

execution := &motor.RuleSetExecution{
    Logger:       logger,
    SilenceLogs:  false,
}
```

--------------------------------

### Launch the vacuum dashboard

Source: https://github.com/daveshanley/vacuum/blob/main/README.md

Run the dashboard command to visualize your OpenAPI specification.

```bash
./vacuum dashboard <your-openapi-spec.yaml | vacuum-report.json.gz>
```

--------------------------------

### Create a new plugin manager

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/plugin.md

Initializes a new manager instance for registering custom functions.

```go
func CreatePluginManager() *Manager
```

```go
import (
    "github.com/daveshanley/vacuum/plugin"
    "github.com/daveshanley/vacuum/model"
)

manager := plugin.CreatePluginManager()
```

--------------------------------

### Define oasOpIdUnique rule

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/functions.md

Defines the Go struct for the unique operation ID rule and provides a YAML configuration example for applying it.

```go
type UniqueOperationId struct{}
```

```yaml
rules:
  operation-operationId-unique:
    given: $.paths[*][get,post,put,delete,patch]
    then:
      function: oasOpIdUnique
```

--------------------------------

### Release Validation with GOWORK=off

Source: https://github.com/daveshanley/vacuum/blob/main/AGENTS.md

Perform release-shaped dependency, install, or CI validation by disabling Go workspaces and setting a temporary cache directory.

```bash
GOWORK=off GOCACHE=/tmp/go-build go test ./...
GOWORK=off GOCACHE=/tmp/go-build go build ./...
```

--------------------------------

### Run Vacuum with Go

Source: https://github.com/daveshanley/vacuum/blob/main/README.md

Execute the latest version of vacuum directly using the Go toolchain.

```bash
go run github.com/daveshanley/vacuum@latest lint <your-openapi-spec.yaml>
```

--------------------------------

### Configure TLS Certificates

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/README.md

Provide custom TLS certificate files for HTTP client configuration.

```go
result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
    HTTPClientConfig: config.HTTPClientConfig{
        CertFile: "cert.pem",
        KeyFile:  "key.pem",
        CAFile:   "ca.pem",
    },
})
```

--------------------------------

### MapBuiltinFunctions Constructor

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/functions.md

Creates the registry containing all standard built-in rule functions.

```go
func MapBuiltinFunctions() Functions
```

--------------------------------

### Load and process custom rulesets in Go

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/plugin.md

Load a ruleset file and apply it to the vacuum motor with custom functions.

```go
// Load ruleset
customRSData, _ := os.ReadFile("custom-ruleset.yaml")
var customRS rulesets.RuleSet
yaml.Unmarshal(customRSData, &customRS)

// Process with custom functions
processedRS := builder.GenerateRuleSetFromSuppliedRuleSet(&customRS)

// Lint with plugin functions
result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
    RuleSet:         processedRS,
    CustomFunctions: customFuncs,
    Spec:            spec,
})
```

--------------------------------

### Handle AsyncAPI and JSON Schema

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/README.md

Detect the specification format and apply the appropriate ruleset.

```go
// Detect format and use appropriate ruleset
format, _ := asyncapi.DetectFormat(spec)
if format == "asyncapi3" {
    rs = builder.GenerateAsyncAPIRecommendedRuleSet()
}

// Lint with AsyncAPI rules
result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
    RuleSet: rs,
    Spec: spec,
})
```

--------------------------------

### Configure Vacuum via YAML

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/README.md

Define linting categories and base URLs using a YAML configuration file.

```yaml
# vacuum.conf.yaml
time: true
base: 'http://example.com'

lint:
  categories: ["operations", "schemas"]
```

--------------------------------

### Compile Vacuum Application

Source: https://github.com/daveshanley/vacuum/blob/main/plugin/sample/README.md

Navigate back to the root of the Vacuum directory and compile the main Vacuum application. This step is necessary to include the custom plugin functionality.

```bash
cd ../../ && go build vacuum.go 
```

--------------------------------

### Build specification metadata

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/asyncapi.md

Constructor function signature for creating specification metadata from a parsed document.

```go
func BuildSpecInfo(
    spec []byte,
    root *yaml.Node,
    version, format string,
) *datamodel.SpecInfo
```

--------------------------------

### Configure Vacuum via Code

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/GETTING_STARTED.md

Customize execution parameters such as timeouts and lookup settings using the RuleSetExecution struct.

```go
result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
    RuleSet:                    rs,
    Spec:                       spec,
    SpecFileName:               "api.yaml",
    Timeout:                    5 * time.Second,
    NodeLookupTimeout:          500 * time.Millisecond,
    AllowLookup:                true,
    Base:                       "https://api.example.com/",
    TurboMode:                  false,
    BuildDeepGraph:             false,
    IgnoreCircularArrayRef:     false,
    IgnoreCircularPolymorphicRef: false,
    ApplyAutoFixes:             false,
    ExtractReferencesSequentially: false,
})
```

--------------------------------

### Configure TLS Authentication in Go

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/GETTING_STARTED.md

Provides certificate, key, and CA files for specs requiring TLS authentication.

```go
import vacuumUtils "github.com/daveshanley/vacuum/utils"

result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
    RuleSet:      rs,
    Spec:         spec,
    SpecFileName: "api.yaml",
    HTTPClientConfig: vacuumUtils.HTTPClientConfig{
        CertFile: "/path/to/cert.pem",
        KeyFile:  "/path/to/key.pem",
        CAFile:   "/path/to/ca.pem",
    },
})
```

--------------------------------

### Configure custom HTTP client for linting

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/motor.md

Provides TLS certificate paths for specifications that require secure remote connections.

```go
// For specs requiring TLS certificates
result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
    RuleSet:      rs,
    Spec:         spec,
    SpecFileName: "spec.yaml",
    HTTPClientConfig: vacuumUtils.HTTPClientConfig{
        CertFile: "/path/to/cert.pem",
        KeyFile:  "/path/to/key.pem",
        CAFile:   "/path/to/ca.pem",
    },
})
```

--------------------------------

### Create Execution Configuration

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/types.md

Configures the execution parameters for a ruleset, including timeouts and base URLs.

```go
exec := &motor.RuleSetExecution{
    RuleSet:      ruleset,
    Spec:         specBytes,
    SpecFileName: "api.yaml",
    Timeout:      5 * time.Second,
    AllowLookup:  true,
    Base:         "https://example.com/",
}
```

--------------------------------

### BuildSpecInfo

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/asyncapi.md

Creates specification metadata from a parsed AsyncAPI document.

```APIDOC
## func BuildSpecInfo(spec []byte, root *yaml.Node, version, format string) *datamodel.SpecInfo

### Description
Creates specification metadata from parsed AsyncAPI document.

### Parameters
- **spec** (`[]byte`) - Required - Raw specification bytes
- **root** (`*yaml.Node`) - Required - Root YAML node
- **version** (`string`) - Required - AsyncAPI version (e.g., "3.0.0")
- **format** (`string`) - Required - Specification format identifier

### Returns
- `*datamodel.SpecInfo` - Specification metadata.
```

--------------------------------

### Generate AsyncAPI Recommended RuleSet

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/rulesets.md

Retrieves the recommended subset of AsyncAPI validation rules.

```go
func (rs RuleSets) GenerateAsyncAPIRecommendedRuleSet() *RuleSet
```

--------------------------------

### Compile Plugin as Shared Library

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/plugin.md

Use the Go build command with the plugin build mode to generate a shared object file.

```bash
# Build as a shared library
go build -buildmode=plugin -o custom.so main.go
```

--------------------------------

### Initialize DefaultFetchConfig

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/utils.md

Retrieves a secure default configuration for fetch requests.

```go
func DefaultFetchConfig() *FetchConfig
```

```go
config := vacuumUtils.DefaultFetchConfig()
config.AllowPrivateNetworks = true  // Allow internal APIs

result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
    FetchConfig: config,
})
```

--------------------------------

### Run Vacuum via Docker

Source: https://github.com/daveshanley/vacuum/blob/main/README.md

Execute the linter by mounting the current directory to the container.

```bash
docker run --rm -v $PWD:/work:ro dshanley/vacuum lint <your-openapi-spec.yaml>
```

--------------------------------

### Display Project File Structure

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/VERIFICATION_REPORT.md

Visual representation of the directory layout for the project documentation.

```text
/workspace/home/output/
├── README.md                          (Overview)
├── GETTING_STARTED.md                (Learning guide)
├── INDEX.md                           (Navigation)
├── types.md                           (Type reference)
├── configuration.md                   (Config reference)
├── DOCUMENTATION_SUMMARY.txt          (Generation summary)
├── VERIFICATION_REPORT.md             (This file)
└── api-reference/
    ├── motor.md                      (Linting engine)
    ├── model.md                      (Core types)
    ├── rulesets.md                  (Rule management)
    ├── functions.md                 (Validators)
    ├── parser.md                    (Parsing)
    ├── asyncapi.md                  (AsyncAPI support)
    ├── plugin.md                    (Plugin system)
    └── utils.md                     (Utilities)
```

--------------------------------

### Apply custom Spectral-compatible rulesets

Source: https://github.com/daveshanley/vacuum/blob/main/README.md

Use the -r or --ruleset flag to specify a ruleset file for linting commands.

```bash
./vacuum lint -r rulesets/examples/norules-ruleset.yaml <your-openapi-spec.yaml>
```

```bash
./vacuum lint -r rulesets/examples/recommended-ruleset.yaml <your-openapi-spec.yaml>
```

```bash
./vacuum lint -r rulesets/examples/specific-ruleset.yaml <your-openapi-spec.yaml>
```

```bash
./vacuum lint -r rulesets/examples/custom-ruleset.yaml <your-openapi-spec.yaml>
```

```bash
./vacuum lint -r rulesets/examples/all-ruleset.yaml <your-openapi-spec.yaml>
```

--------------------------------

### CreateCustomHTTPClient

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/utils.md

Creates an HTTP client configured with the provided TLS settings.

```APIDOC
## CreateCustomHTTPClient

### Description
Creates an HTTP client configured with the provided TLS settings.

### Signature
`func CreateCustomHTTPClient(config HTTPClientConfig) (*http.Client, error)`

### Parameters
- **config** (HTTPClientConfig) - Required - TLS configuration

### Returns
- **client** (*http.Client) - Configured HTTP client
- **error** (error) - Error if configuration is invalid
```

--------------------------------

### Load and Apply Custom Plugin Functions

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/plugin.md

Load the compiled shared library using the plugin manager and pass the custom functions to the RuleSetExecution motor.

```go
import (
    "github.com/daveshanley/vacuum/plugin"
    "github.com/daveshanley/vacuum/motor"
)

// Load plugin
manager, err := plugin.LoadFunctions("./custom.so", false)
if err != nil {
    fmt.Printf("Failed to load plugin: %v\n", err)
    return
}

// Get custom functions
customFuncs := manager.GetCustomFunctions()

// Use in linting
result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
    RuleSet:         rs,
    CustomFunctions: customFuncs,
    Spec:            spec,
})
```

--------------------------------

### Set vacuum configuration via environment variables

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/configuration.md

Override configuration file settings by setting environment variables prefixed with VACUUM_.

```bash
# Enable time display
export VACUUM_TIME=true

# Set base URL
export VACUUM_BASE='http://example.com'

# Skip document validation
export VACUUM_SKIP_DOCUMENT_CHECK=true

# Turbo mode
export VACUUM_TURBO_MODE=true

# Set ruleset
export VACUUM_RULESET='./custom-ruleset.yaml'

# Set ignore file
export VACUUM_IGNORE_FILE='.vacuumignore'

# Disable update check
export VACUUM_NO_UPDATE_CHECK=true
```

--------------------------------

### Configure Auto-Fixes

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/configuration.md

Enables auto-fix functions and demonstrates how to access the modified specification.

```go
execution := &motor.RuleSetExecution{
    ApplyAutoFixes: true, // Apply auto-fix functions
}

// Access fixed spec
if len(result.FixedResults) > 0 {
    os.WriteFile("spec-fixed.yaml", result.ModifiedSpec, 0644)
}
```

--------------------------------

### Perform Programmatic Linting

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/README.md

Apply a recommended ruleset to a byte slice containing an API specification.

```go
// Lint a specification with recommended rules
rs := builder.GenerateOpenAPIRecommendedRuleSet()
result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
    RuleSet: rs,
    Spec: specBytes,
})
```

--------------------------------

### Apply HTTPClientConfig in RuleSetExecution

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/configuration.md

Demonstrates how to pass HTTPClientConfig into the motor.ApplyRulesToRuleSet function.

```go
result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
    RuleSet: rs,
    Spec:    spec,
    HTTPClientConfig: vacuumUtils.HTTPClientConfig{
        CertFile: "/path/to/cert.pem",
        KeyFile:  "/path/to/key.pem",
        CAFile:   "/path/to/ca-bundle.pem",
        Insecure: false, // Always false for production
    },
})
```

--------------------------------

### Generate OpenAPI Recommended RuleSet

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/rulesets.md

Retrieves a curated subset of OpenAPI rules recommended for best practices.

```go
func (rs RuleSets) GenerateOpenAPIRecommendedRuleSet() *RuleSet
```

```go
// Most common usage for linting
recommendedRules := builder.GenerateOpenAPIRecommendedRuleSet()
result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
    RuleSet: recommendedRules,
    Spec:    specBytes,
})
```

--------------------------------

### Set Default Fetch Configuration

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/configuration.md

Define the default timeout and network access settings for fetching resources.

```go
func DefaultFetchConfig() *FetchConfig {
    return &FetchConfig{
        Timeout: 30 * time.Second,
        // AllowPrivateNetworks: false
        // AllowHTTP: false
    }
}
```

--------------------------------

### Load custom functions from a plugin file

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/plugin.md

Loads compiled plugin files into the manager. Ensure the path points to a valid .so, .dylib, or .dll file based on the operating system.

```go
func LoadFunctions(path string, silence bool) (*Manager, error)
```

```go
manager, err := plugin.LoadFunctions("./plugins/custom.so", false)
if err != nil {
    fmt.Printf("Failed to load plugin: %v\n", err)
    return
}

fmt.Printf("Loaded %d functions\n", manager.LoadedFunctionCount())
```

--------------------------------

### Build with Custom Version via ldflags

Source: https://github.com/daveshanley/vacuum/blob/main/BUILD_PACKAGING.md

Builds the vacuum binary with custom version, commit, and date information embedded using ldflags. The `-o vacuum` flag specifies the output binary name. The `.` at the end explicitly targets the current directory.

```bash
./scripts/build-ui-assets.sh
go build -tags html_report_ui -ldflags "-X main.version=<version> -X main.commit=<commit> -X 'main.date=<date>'" \
    -o vacuum
```

```bash
./scripts/build-ui-assets.sh
go build -tags html_report_ui -ldflags "-X main.version=<version> -X main.commit=<commit> -X 'main.date=<date>'" \
    -o vacuum \
    .
```

--------------------------------

### Perform File I/O Operations

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/utils.md

Standard patterns for reading specification files and writing output reports.

```go
// Read specification
spec, err := os.ReadFile("openapi.yaml")
if err != nil {
    fmt.Printf("Failed to read spec: %v", err)
    return
}

// Read ruleset
rulesetData, err := os.ReadFile("ruleset.yaml")
if err != nil {
    fmt.Printf("Failed to read ruleset: %v", err)
    return
}

// Write results
os.WriteFile("report.json", reportBytes, 0644)
```

--------------------------------

### Configure HTTP Client Certificates

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/utils.md

Use this configuration to enforce certificate validation for HTTP clients. Ensure Insecure is set to false for production environments.

```go
// ALWAYS validate certificates in production
config := vacuumUtils.HTTPClientConfig{
    CertFile: "client.crt",
    KeyFile:  "client.key",
    CAFile:   "ca.crt",
    Insecure: false,  // Never true in production
}
```

--------------------------------

### Execute Linting

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/GETTING_STARTED.md

Apply a ruleset to a specification file using the motor package, specifying timeout and remote lookup settings.

```go
result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
    RuleSet:      ruleset,
    SpecFileName: "api.yaml",
    Spec:         specBytes,
    Timeout:      5 * time.Second,
    AllowLookup:  true,  // Allow remote $ref
    Base:         "https://api.example.com/",
})
```

--------------------------------

### Generate Built-in Rulesets

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/GETTING_STARTED.md

Initialize predefined rulesets for OpenAPI, AsyncAPI, or JSON Schema using the builder package.

```go
// Recommended rules (most common)
rs := builder.GenerateOpenAPIRecommendedRuleSet()

// All available rules
rs := builder.GenerateOpenAPIDefaultRuleSet()

// AsyncAPI
rs := builder.GenerateAsyncAPIRecommendedRuleSet()

// JSON Schema
rs := builder.GenerateJSONSchemaRecommendedRuleSet()
```

--------------------------------

### Pull Vacuum Docker Image

Source: https://github.com/daveshanley/vacuum/blob/main/README.md

Download the latest vacuum Docker image from the registry.

```bash
docker pull dshanley/vacuum
```

--------------------------------

### Test AsyncAPI Linting and Motor

Source: https://github.com/daveshanley/vacuum/blob/main/AGENTS.md

Run focused Go tests for AsyncAPI linting, ruleset, and motor components. Use for AsyncAPI linting, ruleset, or context changes.

```bash
go test ./cmd -run 'AsyncAPI|Lint|Report|Dashboard|GenerateRuleset'
go test ./motor -run 'AsyncAPI'
go test ./asyncapi ./functions/asyncapi ./rulesets
```

--------------------------------

### Configure Custom Text Logger

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/configuration.md

Sets up a text handler for stderr with debug level and source attribution enabled, then assigns it to the execution context.

```go
logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
    Level: slog.LevelDebug,
    AddSource: true,
}))

execution := &motor.RuleSetExecution{
    Logger: logger,
}
```

--------------------------------

### Implement an API Naming Convention plugin

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/plugin.md

Create a custom rule function by implementing the required interface for API path validation.

```go
package main

import (
    "strings"
    "github.com/daveshanley/vacuum/model"
    "go.yaml.in/yaml/v4"
)

type ApiNamingConvention struct{}

func (anc *ApiNamingConvention) RunRule(
    nodes []*yaml.Node,
    context model.RuleFunctionContext,
) []model.RuleFunctionResult {
    results := make([]model.RuleFunctionResult, 0)
    
    opts := context.GetOptionsStringMap()
    pattern := opts["pattern"]
    if pattern == "" {
        pattern = "^/api/v[0-9]+/"
    }
    
    for _, node := range nodes {
        if node.Value != "" && !matchesPattern(node.Value, pattern) {
            results = append(results, model.RuleFunctionResult{
                Message:   "API path does not follow naming convention",
                Path:      context.Given.(string),
                RuleId:    context.Rule.Id,
                StartNode: node,
            })
        }
    }
    
    return results
}

func (anc *ApiNamingConvention) GetSchema() model.RuleFunctionSchema {
    return model.RuleFunctionSchema{
        Name: "apiNamingConvention",
        Properties: []model.RuleFunctionProperty{
            {
                Name:        "pattern",
                Description: "Regex pattern for API path names",
            },
        },
    }
}

func (anc *ApiNamingConvention) GetCategory() string {
    return model.FunctionCategoryCustomJS
}

func matchesPattern(path, pattern string) bool {
    return strings.Contains(path, "/api/v")
}

func CustomFunctions() map[string]model.RuleFunction {
    return map[string]model.RuleFunction{
        "apiNamingConvention": &ApiNamingConvention{},
    }
}
```

--------------------------------

### Perform basic linting with motor

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/motor.md

Builds a default ruleset and applies it to a specification file to identify violations.

```go
// 1. Build a ruleset
rs := rulesets.BuildDefaultRuleSetsWithLogger(logger).
    GenerateOpenAPIRecommendedRuleSet()

// 2. Read specification
spec, _ := os.ReadFile("spec.yaml")

// 3. Execute linting
result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
    RuleSet:      rs,
    SpecFileName: "spec.yaml",
    Spec:         spec,
})

// 4. Check results
if result.RuleSetExecution.RuleSet == nil {
    fmt.Println("No violations found!")
}
```

--------------------------------

### Configure Performance Options

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/configuration.md

Adjusts execution performance by toggling modes like TurboMode and parallel reference extraction.

```go
execution := &motor.RuleSetExecution{
    TurboMode:           true,  // Skip expensive rules
    SkipCircularCheck:   false, // Skip circular ref checks
    SkipSchemaErrors:    false, // Skip schema error injection
    ExtractReferencesSequentially: false, // Extract refs in parallel
}
```

--------------------------------

### Implement API Linting Test

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/GETTING_STARTED.md

Demonstrates a standard test case for validating an OpenAPI specification file against recommended rule sets.

```go
func TestAPILinting(t *testing.T) {
    spec, _ := os.ReadFile("testdata/api.yaml")
    
    logger := slog.New(slog.NewTextHandler(io.Discard, nil))
    builder := rulesets.BuildDefaultRuleSetsWithLogger(logger)
    rs := builder.GenerateOpenAPIRecommendedRuleSet()
    
    result := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
        RuleSet:      rs,
        Spec:         spec,
        SpecFileName: "api.yaml",
    })
    
    if result.Results.GetErrorCount() > 0 {
        t.Errorf("Expected no errors, got %d", result.Results.GetErrorCount())
    }
}
```

--------------------------------

### Configure Global Vacuum Flags

Source: https://github.com/daveshanley/vacuum/blob/main/README.md

Define global configuration settings at the top level of the vacuum.conf.yaml file.

```yaml
time: true
base: 'http://example.com'
...
```

--------------------------------

### Define vacuum.conf.yaml configuration

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/configuration.md

Structure global and command-specific settings in a YAML file.

```yaml
# Global settings
time: true
base: 'http://example.com'
silent: false

# Command-specific settings
lint:
  silent: false
  categories: ["operations", "schemas"]

docs:
  output-dir: "./api-docs"

dashboard:
  ignore-file: ".vacuumignore"
```

--------------------------------

### Define FetchConfig struct

Source: https://github.com/daveshanley/vacuum/blob/main/_autodocs/api-reference/utils.md

Configuration structure for JavaScript fetch() requests within custom rule functions.

```go
type FetchConfig struct {
    HTTPClientConfig                    // TLS configuration
    AllowPrivateNetworks bool           // Allow 127.0.0.1, 10.x, 192.168.x
    AllowHTTP            bool           // Allow HTTP (non-HTTPS)
    Timeout              time.Duration  // Request timeout
}
```

--------------------------------

### Compile Custom Go Plugin

Source: https://github.com/daveshanley/vacuum/blob/main/plugin/sample/README.md

Compile the custom Go plugin files into a shared object. Ensure all necessary Go files for the plugin are included in the build command.

```bash
go build -buildmode=plugin boot.go check_single_path.go useless_func.go
```