converter

Author: TristanSpeakEasy

AGENTS.md

@@ -106,6 +106,66 @@ git commit -m "feat: implement prefixEncoding and itemEncoding for OpenAPI 3.2
 3. **Searchability**: Easier to search and filter commits
 4. **Tool Compatibility**: Works better with automated tools and scripts
 
+## Linter Rules
+
+This project uses `golangci-lint` with strict rules. Run `mise lint` to check. The most common violations are listed below. **When you encounter a new common lint pattern not documented here, add it to this section so future sessions avoid the same mistakes.**
+
+### perfsprint — Avoid `fmt.Sprintf` for Simple String Operations
+
+The `perfsprint` linter flags unnecessary `fmt.Sprintf` calls. Use string concatenation or `strconv` instead.
+
+#### ❌ Bad
+
+```go
+// Single %s — just use concatenation
+msg := fmt.Sprintf("prefix: %s", value)
+
+// Single %d — use strconv
+msg := fmt.Sprintf("%d", count)
+
+// Writing formatted string to a writer
+b.WriteString(fmt.Sprintf("hello %s world %d", name, n))
+```
+
+#### ✅ Good
+
+```go
+// String concatenation
+msg := "prefix: " + value
+
+// strconv for numbers
+msg := strconv.Itoa(count)
+
+// fmt.Fprintf writes directly to the writer
+fmt.Fprintf(b, "hello %s world %d", name, n)
+
+// For string-only format with multiple args, concatenation is fine
+b.WriteString(indent + "const x = " + varName + ";\n")
+```
+
+**Rule of thumb:** If `fmt.Sprintf` has a single `%s` or `%d` verb and nothing else complex, replace it with concatenation or `strconv`. If writing to an `io.Writer`/`strings.Builder`, use `fmt.Fprintf` directly instead of `WriteString(fmt.Sprintf(...))`.
+
+### staticcheck — Common Issues
+
+- **QF1012**: Use `fmt.Fprintf(w, ...)` instead of `w.WriteString(fmt.Sprintf(...))` — writes directly to the writer without an intermediate string allocation.
+- **QF1003**: Use tagged `switch` instead of `if-else` chains on the same variable.
+- **S1016**: Use type conversion `TargetType(value)` instead of struct literal when types have identical fields.
+
+### predeclared — Don't Shadow Built-in Identifiers
+
+Avoid using `min`, `max`, `new`, `len`, `cap`, `copy`, `delete`, `error`, `any` as variable names. Use descriptive alternatives like `minVal`, `maxVal`.
+
+### testifylint — Test Assertion Best Practices
+
+- Use `assert.Empty(t, val)` instead of `assert.Equal(t, "", val)`
+- Use `assert.True(t, val)` / `assert.False(t, val)` instead of `assert.Equal(t, true/false, val)`
+- Use `require.Error(t, err)` instead of `assert.Error(t, err)` for error checks
+- Use `assert.Len(t, slice, n)` instead of `assert.Equal(t, n, len(slice))`
+
+### gocritic — Code Style
+
+- Convert `if-else if` chains to `switch` statements when comparing the same variable.
+
 ## Testing
 
 Follow these testing conventions when writing Go tests in this project. Run newly added or modified test immediately after changes to make sure they work as expected before continuing with more work.

cmd/openapi/commands/openapi/convert_rules.go

@@ -0,0 +1,166 @@
+package openapi
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+
+	"github.com/speakeasy-api/openapi/openapi/linter/converter"
+	"github.com/spf13/cobra"
+)
+
+var convertRulesCmd = &cobra.Command{
+	Use:   "convert-rules <config-file>",
+	Short: "Convert Spectral/Vacuum/legacy configs to native linter format",
+	Long: `Convert a Spectral, Vacuum, or legacy Speakeasy lint config into the native
+linter format. This generates:
+
+  - A lint.yaml config file with mapped rule overrides
+  - TypeScript rule files for custom rules that don't have native equivalents
+
+Supported input formats:
+  - Spectral configs (.spectral.yml / .spectral.yaml)
+  - Vacuum configs (Spectral-compatible format)
+  - Legacy Speakeasy lint.yaml (with lintVersion/defaultRuleset/rulesets)
+
+Examples:
+  openapi spec lint convert-rules .spectral.yml
+  openapi spec lint convert-rules .spectral.yml --output ./converted
+  openapi spec lint convert-rules lint.yaml --dry-run
+  openapi spec lint convert-rules .spectral.yml --force`,
+	Args: cobra.ExactArgs(1),
+	Run:  runConvertRules,
+}
+
+var (
+	convertOutput   string
+	convertRulesDir string
+	convertForce    bool
+	convertDryRun   bool
+)
+
+func init() {
+	convertRulesCmd.Flags().StringVarP(&convertOutput, "output", "o", ".", "Output directory for generated files")
+	convertRulesCmd.Flags().StringVar(&convertRulesDir, "rules-dir", "./rules", "Subdirectory for generated .ts rule files")
+	convertRulesCmd.Flags().BoolVarP(&convertForce, "force", "f", false, "Overwrite existing files")
+	convertRulesCmd.Flags().BoolVar(&convertDryRun, "dry-run", false, "Print summary without writing files")
+
+	lintCmd.AddCommand(convertRulesCmd)
+}
+
+func runConvertRules(cmd *cobra.Command, args []string) {
+	configFile := args[0]
+
+	// Parse the input config
+	ir, err := converter.ParseFile(configFile)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error parsing config: %v\n", err)
+		os.Exit(1)
+	}
+
+	// Generate native output
+	result, err := converter.Generate(ir,
+		converter.WithRulesDir(convertRulesDir),
+	)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error generating output: %v\n", err)
+		os.Exit(1)
+	}
+
+	// Print summary
+	printConvertSummary(result, configFile)
+
+	// Print warnings
+	if len(result.Warnings) > 0 {
+		fmt.Println("\nWarnings:")
+		for _, w := range result.Warnings {
+			prefix := ""
+			if w.RuleID != "" {
+				prefix = fmt.Sprintf("[%s] ", w.RuleID)
+			}
+			fmt.Printf("  %s(%s) %s\n", prefix, w.Phase, w.Message)
+		}
+	}
+
+	if convertDryRun {
+		fmt.Println("\n--dry-run: no files written")
+		return
+	}
+
+	// Check for existing files unless --force
+	if !convertForce {
+		configPath := filepath.Join(convertOutput, "lint.yaml")
+		if _, err := os.Stat(configPath); err == nil {
+			fmt.Fprintf(os.Stderr, "Error: %s already exists (use --force to overwrite)\n", configPath)
+			os.Exit(1)
+		}
+		rulesPath := filepath.Join(convertOutput, convertRulesDir)
+		if _, err := os.Stat(rulesPath); err == nil {
+			fmt.Fprintf(os.Stderr, "Error: %s already exists (use --force to overwrite)\n", rulesPath)
+			os.Exit(1)
+		}
+	}
+
+	// Ensure output directory exists
+	if err := os.MkdirAll(convertOutput, 0o755); err != nil { //nolint:gosec
+		fmt.Fprintf(os.Stderr, "Error creating output directory: %v\n", err)
+		os.Exit(1)
+	}
+
+	// Write files
+	if err := result.WriteFiles(convertOutput); err != nil {
+		fmt.Fprintf(os.Stderr, "Error writing files: %v\n", err)
+		os.Exit(1)
+	}
+
+	fmt.Printf("\nFiles written to %s\n", convertOutput)
+}
+
+func printConvertSummary(result *converter.GenerateResult, inputFile string) {
+	fmt.Printf("Converting: %s\n\n", inputFile)
+
+	// Extends
+	if len(result.Config.Extends) > 0 {
+		fmt.Printf("Extends: %v\n", result.Config.Extends)
+	}
+
+	// Rule overrides
+	overrideCount := 0
+	for _, entry := range result.Config.Rules {
+		if entry.Disabled != nil || entry.Severity != nil {
+			overrideCount++
+		}
+	}
+	if overrideCount > 0 {
+		fmt.Printf("Rule overrides: %d\n", overrideCount)
+	}
+
+	// Generated rules
+	if len(result.GeneratedRules) > 0 {
+		ruleIDs := sortedKeys(result.GeneratedRules)
+		fmt.Printf("Generated rules: %d\n", len(result.GeneratedRules))
+		for _, ruleID := range ruleIDs {
+			fmt.Printf("  - %s.ts\n", ruleID)
+		}
+
+		// Files to be written
+		fmt.Println("\nFiles:")
+		fmt.Println("  - lint.yaml")
+		for _, ruleID := range ruleIDs {
+			fmt.Printf("  - %s/%s.ts\n", convertRulesDir, ruleID)
+		}
+	} else {
+		fmt.Println("\nFiles:")
+		fmt.Println("  - lint.yaml")
+	}
+}
+
+func sortedKeys(m map[string]string) []string {
+	keys := make([]string, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	return keys
+}

go.work

@@ -4,5 +4,6 @@ use (
 	.
 	./cmd/openapi
 	./jsonschema/oas3/tests
+	./openapi/linter/converter/tests
 	./openapi/linter/customrules
 )

linter/config.go

@@ -48,6 +48,7 @@ func (c *Config) UnmarshalYAML(value *yaml.Node) error {
 		Rules        []RuleEntry               `yaml:"rules,omitempty"`
 		Categories   map[string]CategoryConfig `yaml:"categories,omitempty"`
 		OutputFormat OutputFormat              `yaml:"output_format,omitempty"`
+		CustomRules  *CustomRulesConfig        `yaml:"custom_rules,omitempty"`
 	}
 	if err := value.Decode(&raw); err != nil {
 		return err
@@ -78,6 +79,7 @@ func (c *Config) UnmarshalYAML(value *yaml.Node) error {
 	c.Rules = raw.Rules
 	c.Categories = raw.Categories
 	c.OutputFormat = raw.OutputFormat
+	c.CustomRules = raw.CustomRules
 	return nil
 }
 

linter/config_test.go

@@ -89,6 +89,20 @@ func TestLoadConfig_MatchRegex(t *testing.T) {
 	assert.Equal(t, regexp.MustCompile(".*title.*").String(), config.Rules[0].Match.String())
 }
 
+func TestLoadConfig_CustomRulesRoundTrip(t *testing.T) {
+	t.Parallel()
+
+	configYAML := `extends: all
+custom_rules:
+  paths:
+    - "./rules/*.ts"
+    - "./extra/*.ts"`
+	config, err := linter.LoadConfig(strings.NewReader(configYAML))
+	require.NoError(t, err, "should load config with custom_rules")
+	require.NotNil(t, config.CustomRules, "custom_rules should survive UnmarshalYAML round-trip")
+	assert.Equal(t, []string{"./rules/*.ts", "./extra/*.ts"}, config.CustomRules.Paths, "custom_rules.paths should be preserved")
+}
+
 func TestConfig_ValidateMissingRuleID(t *testing.T) {
 	t.Parallel()
 

mise-tasks/test

@@ -19,6 +19,8 @@ else
 
     echo "🧪 Running tests in separate modules..."
     (cd jsonschema/oas3/tests && GOWORK=off gotestsum --format testname -- -race ./...)
+    (cd openapi/linter/customrules && GOWORK=off gotestsum --format testname -- -race ./...)
+    (cd openapi/linter/converter/tests && GOWORK=off gotestsum --format testname -- -race ./...)
 fi
 
 echo "✅ All tests passed!"