fix: improve interactive lint fixer controls and exit behavior (#196)

Author: TristanSpeakEasy

.gitignore

@@ -14,4 +14,6 @@ dist/
 # Symlinked from AGENTS.md by mise install
 CLAUDE.md
 
-go.work.sum
+go.work.sum
+
+.mcp.json

README.md

@@ -161,6 +161,9 @@ openapi spec lint ./spec.yaml
 # Lint with custom configuration
 openapi spec lint --config lint.yaml ./spec.yaml
 
+# Interactive lint fixing
+openapi spec lint --fix-interactive ./spec.yaml
+
 # Bundle external references into components section
 openapi spec bundle ./spec.yaml ./bundled-spec.yaml
 

cmd/openapi/commands/openapi/README.md

@@ -69,16 +69,29 @@ openapi spec lint -c ./lint.yaml ./spec.yaml
 
 # Lint with specific rules disabled
 openapi spec lint -d rule-id-1 -d rule-id-2 ./spec.yaml
+
+# Auto-apply non-interactive fixes
+openapi spec lint --fix ./spec.yaml
+
+# Interactive fix mode (s=skip, r=skip rule, e/Esc then Enter=exit)
+openapi spec lint --fix-interactive ./spec.yaml
+
+# Preview fixes without writing changes
+openapi spec lint --fix-interactive --dry-run ./spec.yaml
 ```
 
 **Flags:**
 
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--format` | `-f` | Output format: `text` (default) or `json` |
-| `--config` | `-c` | Path to lint configuration file |
-| `--ruleset` | `-r` | Ruleset to use (default: `all`) |
-| `--disable` | `-d` | Rules to disable (can be specified multiple times) |
+| Flag                | Short | Description                                                                                                                                                       |
+| ------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--format`          | `-f`  | Output format: `text` (default) or `json`                                                                                                                         |
+| `--config`          | `-c`  | Path to lint configuration file                                                                                                                                   |
+| `--ruleset`         | `-r`  | Ruleset to use (default: `all`)                                                                                                                                   |
+| `--disable`         | `-d`  | Rules to disable (can be specified multiple times)                                                                                                                |
+| `--summary`         |       | Print a per-rule summary table of findings                                                                                                                        |
+| `--fix`             |       | Automatically apply non-interactive fixes and write back                                                                                                          |
+| `--fix-interactive` |       | Apply all fixes, prompting for interactive ones (`s`=skip, `r`=skip rule, `e`/Esc then Enter=exit; text prompts support `\` prefix for literal reserved controls) |
+| `--dry-run`         |       | Show what fixes would be applied without changing the file (requires `--fix` or `--fix-interactive`)                                                              |
 
 **What lint checks:**
 
@@ -142,30 +155,30 @@ output_format: text
 
 **Configuration Options:**
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `extends` | `string[]` | Rulesets to extend from (`all`, `recommended`, `security`) |
-| `rules` | `RuleEntry[]` | Individual rule configurations |
-| `categories` | `map[string]CategoryConfig` | Category-level configurations |
-| `custom_rules` | `CustomRulesConfig` | Custom TypeScript/JavaScript rules |
-| `output_format` | `string` | Output format (`text` or `json`) |
+| Option          | Type                        | Description                                                |
+| --------------- | --------------------------- | ---------------------------------------------------------- |
+| `extends`       | `string[]`                  | Rulesets to extend from (`all`, `recommended`, `security`) |
+| `rules`         | `RuleEntry[]`               | Individual rule configurations                             |
+| `categories`    | `map[string]CategoryConfig` | Category-level configurations                              |
+| `custom_rules`  | `CustomRulesConfig`         | Custom TypeScript/JavaScript rules                         |
+| `output_format` | `string`                    | Output format (`text` or `json`)                           |
 
 **Available Rulesets:**
 
-| Ruleset | Description |
-|---------|-------------|
-| `all` | All available rules (default) |
+| Ruleset       | Description                                                        |
+| ------------- | ------------------------------------------------------------------ |
+| `all`         | All available rules (default)                                      |
 | `recommended` | Balanced ruleset - semantic rules, essential style, basic security |
-| `security` | Comprehensive OWASP security rules |
+| `security`    | Comprehensive OWASP security rules                                 |
 
 **Rule Entry Options:**
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `id` | `string` | Exact rule ID to configure |
-| `match` | `string` | Regex pattern to match rule IDs |
-| `severity` | `string` | `error`, `warning`, or `hint` |
-| `disabled` | `bool` | Set to `true` to disable the rule |
+| Option     | Type     | Description                       |
+| ---------- | -------- | --------------------------------- |
+| `id`       | `string` | Exact rule ID to configure        |
+| `match`    | `string` | Regex pattern to match rule IDs   |
+| `severity` | `string` | `error`, `warning`, or `hint`     |
+| `disabled` | `bool`   | Set to `true` to disable the rule |
 
 #### Custom Rules
 
@@ -266,16 +279,16 @@ openapi spec lint -c ./lint.yaml ./spec.yaml
 
 Your rule class must implement the `RuleRunner` interface:
 
-| Method | Required | Description |
-|--------|----------|-------------|
-| `id()` | Yes | Unique rule identifier |
-| `category()` | Yes | Rule category (e.g., `style`, `security`) |
-| `description()` | Yes | Full description of the rule |
-| `summary()` | Yes | Short summary for output |
-| `link()` | No | URL to documentation |
-| `defaultSeverity()` | No | Default severity (`error`, `warning`, `hint`) |
-| `versions()` | No | OpenAPI versions this rule applies to |
-| `run()` | Yes | Execute the rule and return validation errors |
+| Method              | Required | Description                                   |
+| ------------------- | -------- | --------------------------------------------- |
+| `id()`              | Yes      | Unique rule identifier                        |
+| `category()`        | Yes      | Rule category (e.g., `style`, `security`)     |
+| `description()`     | Yes      | Full description of the rule                  |
+| `summary()`         | Yes      | Short summary for output                      |
+| `link()`            | No       | URL to documentation                          |
+| `defaultSeverity()` | No       | Default severity (`error`, `warning`, `hint`) |
+| `versions()`        | No       | OpenAPI versions this rule applies to         |
+| `run()`             | Yes      | Execute the rule and return validation errors |
 
 **Accessing Document Data:**
 
@@ -1245,10 +1258,10 @@ openapi spec query --format json 'schemas | where(isComponent) | take(5)' ./spec
 
 **Flags:**
 
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--format` | | Output format: `table` (default), `json`, `markdown`, or `toon` |
-| `--file` | `-f` | Read query from file instead of argument |
+| Flag       | Short | Description                                                     |
+| ---------- | ----- | --------------------------------------------------------------- |
+| `--format` |       | Output format: `table` (default), `json`, `markdown`, or `toon` |
+| `--file`   | `-f`  | Read query from file instead of argument                        |
 
 For the full query language reference, run `openapi spec query-reference`.
 

cmd/openapi/commands/openapi/lint.go

@@ -99,7 +99,7 @@ func init() {
 	lintCmd.Flags().StringSliceVarP(&lintDisableRules, "disable", "d", nil, "Rule IDs to disable (can be repeated)")
 	lintCmd.Flags().BoolVar(&lintSummary, "summary", false, "Print a per-rule summary table of findings")
 	lintCmd.Flags().BoolVar(&lintFix, "fix", false, "Automatically apply non-interactive fixes and write back")
-	lintCmd.Flags().BoolVar(&lintFixInteractive, "fix-interactive", false, "Apply all fixes, prompting for interactive ones")
+	lintCmd.Flags().BoolVar(&lintFixInteractive, "fix-interactive", false, "Apply all fixes, prompting for interactive ones (s=skip, r=skip rule, e/Esc then Enter=exit; text prompts: prefix \\ for literal)")
 	lintCmd.Flags().BoolVar(&lintDryRun, "dry-run", false, "Show what fixes would be applied without changing the file (requires --fix or --fix-interactive)")
 }
 

jsonschema/oas3/tests/testsuite

@@ -157,11 +157,22 @@ func (e *Engine) ProcessErrors(ctx context.Context, doc *openapi.OpenAPI, errs [
 
 	result := &Result{}
 	modified := make(map[conflictKey]bool)
+	skippedRules := make(map[string]bool)
 
 	for _, fe := range fixable {
 		fix := fe.fix
 		vErr := fe.vErr
 
+		// Skip any remaining fixes for rules the user opted to skip.
+		if skippedRules[vErr.Rule] {
+			result.Skipped = append(result.Skipped, SkippedFix{
+				Error:  vErr,
+				Fix:    fix,
+				Reason: SkipUser,
+			})
+			continue
+		}
+
 		// Check for conflicts at the same location
 		key := conflictKey{Line: vErr.GetLineNumber(), Column: vErr.GetColumnNumber(), Rule: vErr.Rule}
 		if key.Line >= 0 && modified[key] {
@@ -204,6 +215,18 @@ func (e *Engine) ProcessErrors(ctx context.Context, doc *openapi.OpenAPI, errs [
 					})
 					continue
 				}
+				if errors.Is(err, validation.ErrSkipRule) {
+					skippedRules[vErr.Rule] = true
+					result.Skipped = append(result.Skipped, SkippedFix{
+						Error:  vErr,
+						Fix:    fix,
+						Reason: SkipUser,
+					})
+					continue
+				}
+				if errors.Is(err, validation.ErrExitInteractive) {
+					return result, nil
+				}
 				result.Failed = append(result.Failed, FailedFix{
 					Error: vErr, Fix: fix, FixError: err,
 				})

linter/fix/engine.go

@@ -74,10 +74,12 @@ type mockPrompter struct {
 	responses []string
 	err       error
 	called    bool
+	callCount int
 }
 
 func (p *mockPrompter) PromptFix(_ *validation.Error, _ validation.Fix) ([]string, error) {
 	p.called = true
+	p.callCount++
 	return p.responses, p.err
 }
 
@@ -180,6 +182,64 @@ func TestEngine_ModeInteractive_UserSkips(t *testing.T) {
 	assert.False(t, f.applied, "fix should not have been applied")
 }
 
+func TestEngine_ModeInteractive_SkipRuleSkipsRemainingSameRule(t *testing.T) {
+	t.Parallel()
+
+	f1 := &mockInteractiveFix{
+		description: "needs input 1",
+		prompts:     []validation.Prompt{{Type: validation.PromptFreeText, Message: "enter value"}},
+	}
+	f2 := &mockInteractiveFix{
+		description: "needs input 2",
+		prompts:     []validation.Prompt{{Type: validation.PromptFreeText, Message: "enter value"}},
+	}
+	fOtherRule := &mockFix{description: "other rule fix"}
+
+	prompter := &mockPrompter{err: validation.ErrSkipRule}
+	engine := fix.NewEngine(fix.Options{Mode: fix.ModeInteractive}, prompter, nil)
+	result, err := engine.ProcessErrors(t.Context(), &openapi.OpenAPI{}, []error{
+		makeError("test-rule", 1, 1, "issue 1", f1),
+		makeError("test-rule", 2, 1, "issue 2", f2),
+		makeError("other-rule", 3, 1, "issue 3", fOtherRule),
+	})
+
+	require.NoError(t, err, "ProcessErrors should not fail")
+	assert.Len(t, result.Applied, 1, "should still apply fixes from other rules")
+	assert.True(t, fOtherRule.applied, "other rule fix should have been applied")
+	assert.Len(t, result.Skipped, 2, "should skip current and remaining fixes for the rule")
+	assert.False(t, f1.applied, "first skipped fix should not be applied")
+	assert.False(t, f2.applied, "remaining same-rule fix should not be applied")
+	assert.True(t, prompter.called, "prompter should have been called")
+	assert.Equal(t, 1, prompter.callCount, "prompter should only be called for the first same-rule fix")
+}
+
+func TestEngine_ModeInteractive_ExitReturnsPartialResults(t *testing.T) {
+	t.Parallel()
+
+	fApplied := &mockFix{description: "auto fix before exit"}
+	fExit := &mockInteractiveFix{
+		description: "needs input",
+		prompts:     []validation.Prompt{{Type: validation.PromptFreeText, Message: "enter value"}},
+	}
+	fNotProcessed := &mockFix{description: "after exit"}
+
+	prompter := &mockPrompter{err: validation.ErrExitInteractive}
+	engine := fix.NewEngine(fix.Options{Mode: fix.ModeInteractive}, prompter, nil)
+	result, err := engine.ProcessErrors(t.Context(), &openapi.OpenAPI{}, []error{
+		makeError("rule-a", 1, 1, "issue 1", fApplied),
+		makeError("rule-b", 2, 1, "issue 2", fExit),
+		makeError("rule-c", 3, 1, "issue 3", fNotProcessed),
+	})
+
+	require.NoError(t, err, "ProcessErrors should not fail")
+	require.Len(t, result.Applied, 1, "should keep already-applied fixes")
+	assert.True(t, fApplied.applied, "first fix should be applied")
+	assert.False(t, fExit.applied, "interactive fix should not be applied after exit")
+	assert.False(t, fNotProcessed.applied, "fixes after exit should not be processed")
+	assert.Empty(t, result.Failed, "exit should not be treated as failure")
+	assert.Equal(t, 1, prompter.callCount, "prompter should only be called once before exiting")
+}
+
 func TestEngine_DryRun(t *testing.T) {
 	t.Parallel()
 

linter/fix/engine_test.go

@@ -6,6 +6,7 @@ import (
 	"io"
 	"strconv"
 	"strings"
+	"unicode/utf8"
 
 	"github.com/speakeasy-api/openapi/validation"
 )
@@ -66,6 +67,8 @@ func (p *TerminalPrompter) promptChoice(prompt validation.Prompt) (string, error
 		p.writef("    [%d] %s\n", j+1, choice)
 	}
 	p.writef("    [s] Skip\n")
+	p.writef("    [r] Skip remaining fixes for this rule\n")
+	p.writef("    [e] Exit interactive fixing\n")
 
 	for {
 		if prompt.Default != "" {
@@ -80,8 +83,17 @@ func (p *TerminalPrompter) promptChoice(prompt validation.Prompt) (string, error
 		}
 		line = strings.TrimSpace(line)
 
-		if line == "s" || line == "skip" {
+		switch strings.ToLower(line) {
+		case "s", "skip":
 			return "", validation.ErrSkipFix
+		case "r":
+			return "", validation.ErrSkipRule
+		case "e", "exit":
+			return "", validation.ErrExitInteractive
+		}
+
+		if isEscapeInput(line) {
+			return "", validation.ErrExitInteractive
 		}
 
 		if line == "" && prompt.Default != "" {
@@ -90,7 +102,7 @@ func (p *TerminalPrompter) promptChoice(prompt validation.Prompt) (string, error
 
 		idx, err := strconv.Atoi(line)
 		if err != nil || idx < 1 || idx > len(prompt.Choices) {
-			p.writef("  Invalid choice: %s (enter 1-%d or s to skip)\n", line, len(prompt.Choices))
+			p.writef("  Invalid choice: %s (enter 1-%d, s, r, e, or Esc then Enter)\n", line, len(prompt.Choices))
 			continue
 		}
 
@@ -103,16 +115,29 @@ func (p *TerminalPrompter) promptFreeText(prompt validation.Prompt) (string, err
 	if prompt.Default != "" {
 		p.writef(" (default: %s)", prompt.Default)
 	}
-	p.writef(" [s to skip]: ")
+	p.writef(" [s=skip, r=skip rule, e=exit; prefix \\ for literal]: ")
 
 	line, err := p.reader.ReadString('\n')
 	if err != nil {
 		return "", fmt.Errorf("reading input: %w", err)
 	}
 	line = strings.TrimSpace(line)
 
-	if line == "s" || line == "skip" {
-		return "", validation.ErrSkipFix
+	if unescaped, ok := unescapeReservedControlInput(line); ok {
+		line = unescaped
+	} else {
+		switch strings.ToLower(line) {
+		case "s", "skip":
+			return "", validation.ErrSkipFix
+		case "r":
+			return "", validation.ErrSkipRule
+		case "e", "exit":
+			return "", validation.ErrExitInteractive
+		}
+
+		if isEscapeInput(line) {
+			return "", validation.ErrExitInteractive
+		}
 	}
 
 	if line == "" && prompt.Default != "" {
@@ -126,6 +151,33 @@ func (p *TerminalPrompter) promptFreeText(prompt validation.Prompt) (string, err
 	return line, nil
 }
 
+func unescapeReservedControlInput(line string) (string, bool) {
+	if !strings.HasPrefix(line, "\\") {
+		return "", false
+	}
+
+	remainder := strings.TrimPrefix(line, "\\")
+	switch strings.ToLower(remainder) {
+	case "s", "skip", "r", "e", "exit":
+		return remainder, true
+	}
+
+	if isEscapeInput(remainder) {
+		return remainder, true
+	}
+
+	return "", false
+}
+
+func isEscapeInput(line string) bool {
+	if line == "" {
+		return false
+	}
+
+	r, size := utf8.DecodeRuneInString(line)
+	return r == '\x1b' && size == len(line)
+}
+
 func (p *TerminalPrompter) Confirm(message string) (bool, error) {
 	p.writef("%s [y/n]: ", message)